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
# Developer Guide for JS GraphQL IntelliJ Plugin v2
1
+
---
2
+
id: developer-guide
3
+
title: Developer guide
4
+
sidebar_label: Developer guide
5
+
---
2
6
3
7
This developer guide covers how to setup your project to get the most out of the GraphQL language tooling in this plugin.
4
8
@@ -16,7 +20,7 @@ The most important aspect of using the plugin is to configure how schema types a
16
20
If the schema types are not discovered correctly, language features such as completion and error highlighting
17
21
will be based on the wrong type information.
18
22
19
-
Schemas and their types are declared using [GraphQL Type System Definition Language](http://facebook.github.io/graphql/June2018/#sec-Type-System)
23
+
Schemas and their types are declared using [GraphQL Type System Definition Language](https://graphql.github.io/graphql-spec/June2018/#sec-Type-System)
20
24
which is also widely known as GraphQL Schema Definition Language (often abbreviated as SDL).
21
25
22
26
If you're authoring your schemas in SDL, the plugin provides the following features:
@@ -42,68 +46,39 @@ scope is to prevent types from being picked up in more than one GraphQL type reg
42
46
errors as types appear to have been declared more than once. In addition, the scopes prevent non-conflicting types from
43
47
showing up in completions and ensure that validation only recognizes the types that belong to the current schema.
44
48
45
-
The plugin allows you to configure your schema scopes in two different ways:
49
+
The plugin allows you to configure your schema scopes using [graphql-config](https://github.com/prismagraphql/graphql-config) configuration files with `includes` and `excludes` glob patterns
46
50
47
-
- Using the IDE "Settings" page called "Appearance & Behaviour" > ["Scopes"](https://www.jetbrains.com/help/idea/2018.1/settings-scopes.html) with patterns for inclusion and exclusion
48
-
- Using [graphql-config](https://github.com/prismagraphql/graphql-config) configuration files with `includes` and `excludes` glob patterns
51
+
### Example projects ###
49
52
50
-
### Setting up Multi-schema Projects using "Appearance & Behaviour" > "Scopes"
51
-
In a multi-schema project, each schema needs its own separate scope.
52
-
53
-
The recommended structure for multi-schema projects is to place each schema in a separate project module or folder.
54
-
55
-
For example:
56
-
57
-
```
58
-
- project root/
59
-
- product a (schema one)/
60
-
- schema files and graphql aware components
61
-
- product b (schema two)/
62
-
- schema files and graphql aware components
63
-
```
64
-
65
-
With this structure there is no need to use exclude patterns.
66
-
67
-
To setup the project, Open "Settings" > "Language & Frameworks" > "GraphQL" and select the "Multiple schemas".
68
-
69
-
The scopes can be created via the "Edit scopes" link:
70
-
71
-
- Click "Add scope"
72
-
- Click Shared scope
73
-
- Name it the same as the folder
74
-
- Select "Project" in the drop down above the project tree
75
-
- Select the "product a (schema one)" folder and click the "Include Recursively" button on the right
76
-
- Repeat for other schemas
77
-
78
-
Given a file which contains GraphQL, the plugin finds the first matching schema scope based on the file name, and then
79
-
proceeds with schema discovery by processing only the files that the scope accepts.
80
-
81
-
__Points to consider__:
82
-
- You don't have to restrict the patterns to specific file extensions since the plugin only searches relevant file types
83
-
- If you do limit to file extensions, make sure you include file extensions for components that use injected GraphQL, e.g. `.jsx`
84
-
- When adding scopes, use the "Shared" scopes to create scopes that can be checked into source control and used by other
85
-
developers on the project
86
-
- If you have created scopes for uses other than GraphQL schema discovery, you should place the GraphQL scopes at the top
87
-
of the list since the first matching scope is used by this plugin
53
+
See https://github.com/jimkyndemeyer/graphql-config-examples for example uses of `.graphqlconfig` to control schema discovery.
88
54
89
55
### Setting up Multi-schema Projects using graphql-config
90
-
The second option for multi-schema projects is graphql-config. With graphql-config you don't get the scopes UI which
91
-
displays the files in the scopes, but it may be the better option if you use other tools that support graphql-config.
92
-
93
-
To setup the project, Open "Settings" > "Language & Frameworks" > "GraphQL" and select the "graphql-config".
94
-
95
56
Please familiarize yourself with the [graphql-config format](https://github.com/prismagraphql/graphql-config/blob/master/specification.md)
96
57
before proceeding.
97
58
98
59
The next step is to decide where to place the `.graphqlconfig` file. The config file controls schema discovery from the
99
60
directory it's placed in, as well as any sub folders that don't have their own `.graphqlconfig`.
100
61
101
-
To create a `.graphqlconfig` file, right click a folder and select "New GraphQL Configuration File".
62
+
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".
102
63
103
64
Depending on your preference, you can use a single `.graphqlconfig` file in a folder that is a parent to each schema
104
65
folder, or you can place `.graphqlconfig` files in each schema folder.
With this approach the location of the config files creates separate scopes for the two schemas.
80
+
81
+
__Option B: Single config file:__
107
82
108
83
```
109
84
- project root/
@@ -129,19 +104,6 @@ With a single config file you need to separate the schemas using the `includes`
129
104
}
130
105
```
131
106
132
-
__Option B: Multiple config files:__
133
-
134
-
```
135
-
- project root/
136
-
- product a (schema one)/
137
-
- .graphqlconfig <-----
138
-
- schema files and graphql aware components
139
-
- product b (schema two)/
140
-
- .graphqlconfig <-----
141
-
- schema files and graphql aware components
142
-
```
143
-
144
-
With this approach the location of the config files creates separate scopes for the two schemas.
145
107
146
108
### Working with GraphQL Endpoints and Scratch Files
147
109
@@ -156,16 +118,26 @@ toolbar button in the top left side of the scratch file editor.
156
118
See https://github.com/prisma/graphql-config#specifying-endpoint-info for the expected format of endpoint details such as
157
119
the URL, headers etc.
158
120
159
-
GraphQL scratch files use the following rules for schema discovery and endpoints:
121
+
The following example is from [graphql-config-examples/remote-schema-introspection](https://github.com/jimkyndemeyer/graphql-config-examples/tree/master/remote-schema-introspection)
122
+
123
+
It demonstrates how to use the endpoints configured in `.graphqlconfig` to fetch an existing remote schema.
124
+
125
+
126
+
127
+
With `introspect: true` the plugin asks at project startup whether to update the local schema using the configured endpoint.
128
+
129
+
130
+
131
+
The update works by sending an introspection query to the endpoint, and then writing the result to the configured `schemaPath`.
132
+
133
+
The latest introspection query can easily be re-run using the schemas panel:
160
134
161
-
- If there is a single `.graphqlconfig` the scratch file automatically uses the schema and endpoints from that configuration
162
-
- For a project with multiple `.graphqlconfig` files, add the following GraphQL comment to your scratch file to pick the relevant `.graphqlconfig`:
163
-
-`# .graphqlconfig=<absolute path to your config dir>\.graphqlconfig`
164
-
- In case no matching `.graphqlconfig` was found, the project base dir will be used for schema discovery, and no endpoints
165
-
will be available for queries or other operations
135
+
166
136
167
-
### ---- TODO BELOW THIS LINE ----
137
+
Introspection queries can also be executed by double-clicking endpoints in the schemas tree view:
168
138
169
-
## Breaking changes from v1
139
+
170
140
171
-
## Troublshooting
141
+
__Notes and comments__
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 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.
143
+
- Tip: The re-run introspection action can be bound to a keyboard shortcut for convienience
0 commit comments