You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+71-44Lines changed: 71 additions & 44 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,64 +1,84 @@
1
1
2
2
3
3
# GraphQL IntelliJ Plugin
4
-
GraphQL language support for [WebStorm](https://www.jetbrains.com/webstorm/), [IntelliJ IDEA](https://www.jetbrains.com/idea/) and other [IDEs based on the IntelliJ Platform](https://www.jetbrains.com/products/#type=ide). The plugin works with all IDEs in the IntelliJ Platform.
4
+
GraphQL language support for [WebStorm](https://www.jetbrains.com/webstorm/), [IntelliJ IDEA](https://www.jetbrains.com/idea/) and all other
5
+
[IDEs](https://www.jetbrains.com/products/#type=ide). The plugin works with all IDEs in the IntelliJ Platform.
5
6
6
7
## Prerequisites & Installation
7
8
### Prerequisites
8
-
The plugin and this documentation assume you are already familiar with the GraphQL language. If you're not, please visit the official [graphql.org](https://graphql.org/) website first.
9
-
The plugin works out of the box with popular GraphQL clients such as [Apollo GraphQL](https://www.apollographql.com/) and [Relay](https://facebook.github.io/relay/), but you're free to choose your client and server frameworks.
9
+
The plugin and this documentation assume you are already familiar with the GraphQL language. If you're not, please visit the official
The plugin works out of the box with popular GraphQL clients such as [Apollo GraphQL](https://www.apollographql.com/) and
12
+
[Relay](https://facebook.github.io/relay/), but you're free to choose your client and server framework.
10
13
### Installation
11
-
The plugin is published to the [JetBrains Plugin Repository](https://plugins.jetbrains.com/plugin/8097-js-graphql).
14
+
The plugin is available from [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/8097-js-graphql).
12
15
You can install it directly from your IDE via the `File | Settings/Preferences | Plugins` screen.
13
16
On the `Marketplace` tab simply search for `graphql` and select the `GraphQL` suggestion:
14
17
15
18
16
19
## Developer guide
17
-
This developer guide covers how to setup your project to get the most out of the GraphQL language tooling in this plugin.
20
+
This developer guide covers how to set up your project to get the most out of the GraphQL language tooling in this plugin.
18
21
19
-
The main features of the plugin are:
20
-
- Full language support for GraphQL Specification including the Schema Definition Language (SDL)
21
-
- Schema-aware completion, error highlighting, code-formatting, folding, commenter, and brace-matching and documentation
22
+
The main features of this plugin include:
23
+
- Full language support for GraphQL Specification including the Schema Definition Language (SDL).
24
+
- Schema-aware completion, error highlighting, and documentation.
25
+
- Syntax highlighting, code-formatting, folding, commenter, and brace-matching.
22
26
23
27
24
28
25
29
26
-
- The plugin [discovers your local schema](#project-structure-and-schema-discovery) on the fly. Remote schemas are easily fetched using introspection. Introspect GraphQL endpoints to generate schema declaration files using the GraphQL Type System Definition Language
27
-
- Support for [multi-schema projects](#setting-up-multi-schema-projects-using-graphql-config) using configurable project scopes or graphql-config files Schema discovery is configured using [graphql-config v2](https://github.com/kamilkisiela/graphql-config/tree/legacy) files, including support for multi-schema projects
28
-
- Built-in support for [Relay](https://facebook.github.io/relay/) and [Apollo](https://www.apollographql.com/) projects: `graphql` and `gql` tagged template literals in JavaScript and TypeScript are automatically recognized as GraphQL
29
-
- Execute queries using variables against configurable endpoints, including support for custom headers and environment variables
30
+
- The plugin [discovers your local schema](#project-structure-and-schema-discovery) on the fly. Remote schemas are easily fetched using
31
+
introspection. You can introspect GraphQL endpoints to generate schema declaration files using the GraphQL Type System Definition Language.
32
+
- Support for [multi-schema projects](#setting-up-multi-schema-projects-using-graphql-config) using configurable project scopes or
33
+
`graphql-config` files. Schema discovery is configured using [graphql-config v2](https://github.com/kamilkisiela/graphql-config/tree/legacy)
34
+
files, which includes support for multi-schema projects.
35
+
- Built-in support for [Relay](https://facebook.github.io/relay/) and [Apollo](https://www.apollographql.com/) projects: `graphql` and `gql`
36
+
tagged template literals in JavaScript and TypeScript are automatically recognized as GraphQL.
37
+
- Execute queries using variables against configurable endpoints, including support for custom headers and environment variables.
30
38
31
39
32
-
-`Find Usages` and `Go to Declaration` for schema types, fields, and fragments
40
+
-`Find Usages` and `Go to Declaration` for schema types, fields, and fragments.
33
41
34
42
35
43
-`Structure view` to navigate GraphQL files
36
-
- Load variables from shell or `.env` files. Supported file names: `.env.local`,`.env.development.local`,`.env.development`,`.env.dev.local`,`.env.dev`,`.env`
37
-
- Built-in Relay and Apollo Federation type definitions (You need to enable it in settings)
44
+
- Load variables from shell or `.env` files. Supported file names: `.env.local`,`.env.development.local`,`.env.development`,
45
+
`.env.dev.local`,`.env.dev`,`.env`
46
+
- Built-in `Relay`, `Federation`, and `Apollo Kotlin` type definitions (You need to enable it in `Preferences / Settings | Languages & Frameworks |
47
+
GraphQL`).
38
48
39
49
40
50
41
-
The most important aspect of using the plugin is to configure how schema types are discovered. If the schema types are not discovered correctly, language features such as completion and error highlighting will be based on the wrong type information.
51
+
It is important to configure how the schema types are discovered. If the schema types are not discovered correctly, language features such
52
+
as completion and error highlighting will be based on the wrong type information.
42
53
43
-
Schemas and their types are declared using GraphQL Type System Definition Language which is also widely known as GraphQL Schema Definition Language (often abbreviated as SDL).
44
-
If you're authoring your schemas in SDL, the plugin provides the following features:
45
-
- Completion on types when defining fields, arguments, implemented interfaces etc.
46
-
- Error highlighting of schema errors such as unknown types, wrong use of types, missing fields when implementing interfaces
47
-
- Find usages in SDL and refactoring such as rename which will update the relevant queries, mutations etc.
54
+
Schemas and their types are declared using GraphQL Type System Definition Language, which is also widely known as GraphQL Schema Definition
55
+
Language (often abbreviated as SDL). If you're authoring your schemas in SDL, the plugin provides the following features:
56
+
- Completion for types when defining fields, arguments, implemented interfaces, and so on.
57
+
- Error highlighting of schema errors such as unknown types, wrong use of types, and missing fields when implementing interfaces.
58
+
- Find usages in SDL and refactoring such as rename, which will update the relevant queries, mutations, and so on.
48
59
49
-
For use cases where you don't declare the schema in the project, an introspection query can be executed against a GraphQL endpoint URL to write the schema to a .graphql file as SDL. See Working with GraphQL Endpoints.
60
+
For use cases where you don't declare the schema in the project, an introspection query can be executed against a GraphQL endpoint URL to
61
+
write the schema to a .graphql file as SDL. See [Working with GraphQL Endpoints](#working-with-graphql-endpoints-and-scratch-files).
50
62
## Project Structure and Schema Discovery
51
-
By default, the plugin assumes that your project only contains a single schema. If this is the case, you don't need to take any action in terms of schema discovery. For a single-schema project, schema types are discovered as follows:
52
-
All `.graphql` files in the "Project files" scope are processed for type definitions which are added to a singleton type registry
53
-
If the IDE has JavaScript language support, injected GraphQL strings in the "Project files" scope are processed for all JavaScript file types. File extensions include `.js`, `.jsx`, `.ts`, and `.tsx`. Injected GraphQL is found based on Tagged Template Literals with one of the following tags: `graphql`, `.gql`, and `Relay.QL`.
54
-
55
-
For projects with multiple schemas, developers have to configure a scope for each schema. The purpose of a schema-specific scope is to prevent types from being picked up in more than one GraphQL type registry, which would likely result in validation errors as types appear to have been declared more than once. In addition, the scopes prevent non-conflicting types from showing up in completions and ensure that validation only recognizes the types that belong to the current schema.
56
-
The plugin allows you to configure your schema scopes using graphql-config v2 configuration files with `includes` and `excludes` glob patterns
63
+
By default, the plugin assumes that your project contains a single schema. If this is the case, you don't need to perform any actions in
64
+
terms of schema discovery. For a single-schema project, schema types are discovered as follows: All `.graphql` files in the "Project files"
65
+
scope are processed for type definitions, which are added to a singleton type registry. If the IDE has JavaScript language support, injected
66
+
GraphQL strings in the `Project files` scope are processed for all JavaScript file types. File extensions include `.js`, `.jsx`, `.ts`,
67
+
and `.tsx.`
68
+
Injected GraphQL is found based on `Tagged Template Literals` with one of the following tags: `graphql`, `.gql`, or `Relay.QL`.
69
+
For projects with multiple schemas, developers have to configure a scope for each schema. The purpose of a schema-specific scope is to
70
+
prevent types from being picked up in more than one GraphQL type registry, which would likely result in validation errors. This is because
71
+
these types will appear to have been declared more than once. In addition, the scopes prevent non-conflicting types from showing up in
72
+
completions and ensure that validation only recognizes the types that belong to the current schema. The plugin allows you to configure your
73
+
schema scopes using `graphql-config v2` configuration files with `includes` and `excludes` glob patterns.
57
74
### Setting up Multi-schema Projects using graphql-config
58
-
Please familiarize yourself with the [graphql-config v2](https://github.com/kamilkisiela/graphql-config/tree/legacy/specification.md) format before proceeding.
59
-
The next step is to decide where to place the `.graphqlconfig` file. The config file controls schema discovery from the directory it's placed in, as well as any sub folders that don't have their own .graphqlconfig.
60
-
To create a `.graphqlconfig` file, right-click a folder and select "New GraphQL Configuration File" or use the "+" Button in the GraphQL Tool window tab called "Schemas and Project Structure".
61
-
Depending on your preference, you can use a single `.graphqlconfig` file in a folder that is a parent to each schema folder, or you can place .graphqlconfig files in each schema folder.
75
+
Please familiarize yourself with the [graphql-config v2](https://github.com/kamilkisiela/graphql-config/tree/legacy/specification.md) format
76
+
before proceeding.
77
+
The next step is to decide where to place the `.graphqlconfig` file. The config file controls schema discovery from the directory it's placed
78
+
in, as well as any subfolders that don't have their own `.graphqlconfig`. To create a `.graphqlconfig` file, right-click a folder and select
79
+
`New GraphQL Configuration File` or use the "+" button in the `GraphQL Tool` window tab named `Schemas` and `Project Structure`. Depending on your
80
+
preference, you can use a single `.graphqlconfig` file in a folder that is a parent to each schema folder, or you can place `.graphqlconfig`
@@ -83,7 +103,7 @@ With this approach the location of the config files creates separate scopes for
83
103
- schema files and graphql aware components
84
104
```
85
105
86
-
With a single config file you need to separate the schemas using the includes globs of the projects field:
106
+
With a single config file you need to separate the schemas using the `includes` globs of the projects field:
87
107
```json
88
108
{
89
109
"projects": {
@@ -97,27 +117,33 @@ With a single config file you need to separate the schemas using the includes gl
97
117
}
98
118
```
99
119
100
-
See https://github.com/jimkyndemeyer/graphql-config-examples for example uses of `.graphqlconfig` to control schema discovery.
120
+
See https://github.com/jimkyndemeyer/graphql-config-examples for example of uses of `.graphqlconfig` to control schema discovery.
101
121
102
122
## Working with GraphQL Endpoints and Scratch Files
103
-
You can use GraphQL scratch files to work with your schema outside product code, e.g. by writing temporary queries to test resolvers.
104
-
To run queries or mutations against your GraphQL endpoint, add your endpoint details to a `.graphqlconfig` file. If you don't already have a config file, you can create one by right-clicking on your project base dir and choosing "New" - "GraphQL Configuration File". If you already have a config file, you can jump to it using the "Edit .graphqlconfig" toolbar button in the top left side of the scratch file editor.
105
-
See https://github.com/kamilkisiela/graphql-config/tree/legacy#specifying-endpoint-info for the expected format of endpoint details such as the URL, headers etc.
106
-
107
-
The following example is from graphql-config-examples/remote-schema-introspection
123
+
You can use GraphQL scratch files to work with your schema outside product code, for example, for writing temporary queries to test
124
+
resolvers. To run queries or mutations against your GraphQL endpoint, add your endpoint details to a `.graphqlconfig` file. If you don't
125
+
already have a config file, you can create one by right-clicking on your project base dir and choosing `New | GraphQL Configuration File`.
126
+
If you already have a config file, you can jump to it using the `Edit .graphqlconfig` toolbar button in the top left of the scratch file
127
+
editor. See https://github.com/kamilkisiela/graphql-config/tree/legacy#specifying-endpoint-info for the expected format of the endpoint
128
+
details such as the URL, headers, and so on.
129
+
The following example is from [graphql-config-examples/remote-schema-introspection](https://github.com/jimkyndemeyer/graphql-config-examples).
108
130
It demonstrates how to use the endpoints configured in `.graphqlconfig` to fetch an existing remote schema.
109
131
110
132
133
+
111
134
With `introspect: true` the plugin asks at project startup whether to update the local schema using the configured endpoint.
112
135
113
-
The update works by sending an introspection query to the endpoint, and then writing the result to the configured schemaPath.
136
+
The update works by sending an introspection query to the `endpoint`, and then writing the result to the configured `schemaPath`.
114
137
115
-
Introspection queries can also be executed by double-clicking endpoints in the schemas tree view:
138
+
Introspection queries can also be executed by double-clicking `Endpoints` in the schemas tree view:
- If you're both developing the server schema and consuming it in a client, e.g. via component queries, you'll get the best tooling by having your schema expressed using GraphQL Schema Definition Language directly in your project. With that setup the plugin immediately discovers your schema, and you don't have to perform an introspection after server schema changes.
120
-
- Tip: The re-run introspection action can be bound to a keyboard shortcut for convenience
142
+
If you're both developing the server schema and consuming it in a client, e.g. via component queries, you'll get the best tooling by having
143
+
your schema expressed using GraphQL Schema Definition Language directly in your project. With this setup, the plugin immediately discovers
144
+
your schema and you don't have to perform an introspection after the server schema changes.
145
+
146
+
Tip: The re-run introspection action can be bound to a keyboard shortcut for convenience.
121
147
122
148
## Injections
123
149
@@ -155,7 +181,8 @@ This plugin was heavily inspired by [GraphiQL](https://github.com/graphql/graphi
155
181
156
182
A number of language features such as query and schema validation are powered by [graphql-java](https://github.com/graphql-java/graphql-java).
157
183
158
-
A thanks also goes out to the [Apollo](https://github.com/apollographql) and [Prisma](https://github.com/prisma) teams for their continued efforts to improve the GraphQL Developer Experience.
184
+
A thanks also goes out to the [Apollo](https://github.com/apollographql) and [Prisma](https://github.com/prisma) teams for their continued
185
+
efforts to improve the GraphQL developer experience.
159
186
160
187
And finally, a thank you to the [JetBrains WebStorm team](https://twitter.com/WebStormIDE) and the Alpha/Beta testers for all their help.
0 commit comments