Skip to content

Commit 61d91a7

Browse files
acaoacao
committed
docs: pluck some docs improvements from the next phase
1 parent 479203c commit 61d91a7

File tree

3 files changed

+82
-194
lines changed

3 files changed

+82
-194
lines changed

‎packages/graphql-language-service-server/README.md

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -157,7 +157,7 @@ module.exports = {
157157
// note that this file will be loaded by the vscode runtime, so the node version and other factors will come into play
158158
customValidationRules: require('./config/customValidationRules'),
159159
languageService: {
160-
// should the language service read schema for definition lookups from a cached file based on graphql config output?
160+
// this is enabled by default if non-local files are specified in the project `schema`
161161
// NOTE: this will disable all definition lookup for local SDL files
162162
cacheSchemaFileForLookup: true,
163163
// undefined by default which has the same effect as `true`, set to `false` if you are already using // `graphql-eslint` or some other tool for validating graphql in your IDE. Must be explicitly `false` to disable this feature, not just "falsy"
@@ -237,14 +237,14 @@ via `initializationOptions` in nvim.coc. The options are mostly designed to
237237
configure graphql-config's load parameters, the only thing we can't configure
238238
with graphql config. The final option can be set in `graphql-config` as well
239239

240-
| Parameter | Default | Description |
241-
| ----------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
242-
| `graphql-config.load.baseDir` | workspace root or process.cwd() | the path where graphql config looks for config files |
243-
| `graphql-config.load.filePath` | `null` | exact filepath of the config file. |
244-
| `graphql-config.load.configName` | `graphql` | config name prefix instead of `graphql` |
245-
| `graphql-config.load.legacy` | `true` | backwards compatibility with `graphql-config@2` |
246-
| `graphql-config.dotEnvPath` | `null` | backwards compatibility with `graphql-config@2` |
247-
| `vscode-graphql.cacheSchemaFileForLookup` | `false` | generate an SDL file based on your graphql-config schema configuration for schema definition lookup and other features. useful when your `schema` config are urls |
240+
| Parameter | Default | Description |
241+
| ----------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
242+
| `graphql-config.load.baseDir` | workspace root or process.cwd() | the path where graphql config looks for config files |
243+
| `graphql-config.load.filePath` | `null` | exact filepath of the config file. |
244+
| `graphql-config.load.configName` | `graphql` | config name prefix instead of `graphql` |
245+
| `graphql-config.load.legacy` | `true` | backwards compatibility with `graphql-config@2` |
246+
| `graphql-config.dotEnvPath` | `null` | backwards compatibility with `graphql-config@2` |
247+
| `vscode-graphql.cacheSchemaFileForLookup` | `true` if `schema` contains non-sdl files or urls | generate an SDL file based on your graphql-config schema configuration for schema definition lookup and other features. enabled by default when your `schema` config are urls or introspection json, or if you have any non-local SDL files in `schema` |
248248

249249
all the `graphql-config.load.*` configuration values come from static
250250
`loadConfig()` options in graphql config.

‎packages/vscode-graphql/README.md

Lines changed: 58 additions & 170 deletions
Original file line numberDiff line numberDiff line change
@@ -7,109 +7,77 @@ Ecosystem with VSCode for an awesome developer experience.
77

88
![](https://camo.githubusercontent.com/97dc1080d5e6883c4eec3eaa6b7d0f29802e6b4b/687474703a2f2f672e7265636f726469742e636f2f497379504655484e5a342e676966)
99

10-
### General features
11-
12-
> _Operation Execution will be re-introduced in a new extension_
13-
14-
- Load the extension on detecting `graphql-config file` at root level or in a
15-
parent level directory
16-
- Load the extension in `.graphql`, `.gql files`
17-
- Load the extension detecting `gql` tag in js, ts, jsx, tsx, vue files
18-
- Load the extension inside `gql`/`graphql` fenced code blocks in markdown files
19-
- NO LONGER SUPPORTED - execute query/mutation/subscription operations, embedded
20-
or in graphql files - we will be recommending other extensions for this.
21-
- pre-load schema and document definitions
22-
- Support [`graphql-config`](https://graphql-config.com/) files with one project
23-
and multiple projects (multi-workspace roots with multiple graphql config
24-
files not yet supported)
25-
- the language service re-starts on saved changes to vscode settings and/or
26-
graphql config!
27-
28-
### `.graphql`, `.gql` file extension support
10+
### `.graphql`, `.gql` file extension support and `gql`/`graphql` tagged template literal support for tsx, jsx, ts, js
2911

30-
- syntax highlighting (type, query, mutation, interface, union, enum, scalar,
31-
fragments, directives)
12+
- syntax highlighting (provided by `vscode-graphql-syntax`)
3213
- autocomplete suggestions
3314
- validation against schema
3415
- snippets (interface, type, input, enum, union)
3516
- hover support
3617
- go to definition support (input, enum, type)
3718
- outline support
3819

39-
### `gql`/`graphql` tagged template literal support for tsx, jsx, ts, js
20+
## Getting Started
4021

41-
- syntax highlighting (type, query, mutation, interface, union, enum, scalar,
42-
fragments, directives)
43-
- autocomplete suggestions
44-
- validation against schema
45-
- snippets
46-
- hover support
47-
- go to definition for fragments and input types
48-
- outline support
22+
> **This extension requires a graphql-config file**.
4923
50-
## Usage
24+
To support language features like completion and "go-to definition" across multiple files,
25+
please include `documents` in the `graphql-config` file default or per-project
5126

52-
**This extension requires a graphql-config file**.
27+
### Simplest Config Example
5328

54-
Install the
55-
[VSCode GraphQL Extension](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql).
56-
57-
(Watchman is no longer required, you can uninstall it now)
29+
```yaml
30+
# .graphqlrc.yml or graphql.config.yml
31+
schema: 'schema.graphql'
32+
documents: 'src/**/*.{graphql,js,ts,jsx,tsx}'
33+
```
5834
59-
As of `[email protected]` we support `graphql-config@3`. You can read more
60-
about that [here](https://www.graphql-config.com/docs/user/user-usage). Because
61-
it now uses `cosmiconfig` there are plenty of new options for loading config
62-
files:
35+
`package.json`:
6336

37+
```json
38+
"graphql": {
39+
"schema": "https://localhost:3001",
40+
"documents": "**/*.{graphql,js,ts,jsx,tsx}"
41+
},
6442
```
65-
graphql.config.json
66-
graphql.config.js
67-
graphql.config.yaml
68-
graphql.config.yml
69-
.graphqlrc (YAML or JSON)
70-
.graphqlrc.json
71-
.graphqlrc.yaml
72-
.graphqlrc.yml
73-
.graphqlrc.js
74-
graphql property in package.json
75-
```
76-
77-
the file needs to be placed at the project root by default, but you can
78-
configure paths per project. see the FAQ below for details.
7943

80-
Previous versions of this extension support `graphql-config@2` format, which
81-
follows
82-
[legacy configuration patterns](https://github.com/kamilkisiela/graphql-config/tree/legacy#usage)
44+
```ts
45+
// .graphqlrc.ts or graphql.config.ts
46+
export default {
47+
schema: 'schema.graphql',
48+
documents: '**/*.{graphql,js,ts,jsx,tsx}',
49+
};
50+
```
8351

84-
If you need legacy support for `.graphqlconfig` files or older graphql-config
85-
formats, see [this FAQ answer](#legacy). If you are missing legacy
86-
`graphql-config` features, please consult
87-
[the `graphql-config` repository](https://github.com/kamilkisiela/graphql-config).
52+
## Additional Features
8853

89-
To support language features like "go-to definition" across multiple files,
90-
please include `documents` key in the `graphql-config` file default or
91-
per-project (this was `include` in 2.0).
54+
- Loads the LSP server upon detecting a `graphql-config` file at root level or in a
55+
parent level directory, or a `package.json` file with `graphql` config
56+
- Loads `.graphql`, `.gql` files, and detects `gql`, `graphql` tags and `/** GraphQL */` and `#graphql` comments in js, ts, jsx, tsx, vue files
57+
- pre-load schema and fragment definitions
58+
- Support [`graphql-config`](https://graphql-config.com/) files with one project
59+
and multiple projects (multi-workspace roots with multiple graphql config
60+
files not yet supported)
61+
- the language service re-starts on saved changes to vscode settings and/or
62+
graphql config!
9263

9364
## Configuration Examples
9465

9566
For more help with configuring the language server,
9667
[the language server readme](https://github.com/graphql/graphiql/tree/main/packages/graphql-language-service-server/README.md)
9768
is the source of truth for all settings used by all editors which use the
98-
language server.
69+
language server. The [`graphql-config`](https://graphql-config.com/) docs are also very helpful.
9970

100-
### Simple Example
71+
### Advanced Example
10172

102-
```yaml
103-
# .graphqlrc.yml
104-
schema: 'schema.graphql'
105-
documents: 'src/**/*.{graphql,js,ts,jsx,tsx}'
106-
```
73+
Multi-project can be used for both local files, URL defined schema, or both
10774

108-
### Advanced Example
75+
```ts
76+
import dotenv from 'dotenv';
77+
dotenv.config();
10978
110-
```js
111-
// graphql.config.js
112-
module.exports = {
79+
// .graphqlrc.ts or graphql.config.ts
80+
export default {
11381
projects: {
11482
app: {
11583
schema: ['src/schema.graphql', 'directives.graphql'],
@@ -119,15 +87,15 @@ module.exports = {
11987
schema: 'src/generated/db.graphql',
12088
documents: ['src/db/**/*.graphql', 'my/fragments.graphql'],
12189
extensions: {
122-
codegen: [
123-
{
124-
generator: 'graphql-binding',
125-
language: 'typescript',
126-
output: {
127-
binding: 'src/generated/db.ts',
90+
// for use with `vscode-graphql-execution`, for example:
91+
endpoints: {
92+
default: {
93+
url: 'https://localhost:3001/graphql/',
94+
headers: {
95+
Authorization: `Bearer ${process.env.API_TOKEN}`,
12896
},
12997
},
130-
],
98+
},
13199
},
132100
},
133101
},
@@ -139,66 +107,9 @@ is also valid.
139107

140108
## Frequently Asked Questions
141109

142-
<span id="legacy" />
143-
144-
### I can't load `.graphqlconfig` files anymore
145-
146-
> Note: this option has been set to be enabled by default, however
147-
> `graphql-config` maintainers do not want to continue to support the legacy
148-
> format (mostly kept for companies where intellij users are stuck on the old
149-
> config format), so please migrate to the new `graphql-config` format as soon
150-
> as possible!
151-
152-
If you need to use a legacy config file, then you just need to enable legacy
153-
mode for `graphql-config`:
154-
155-
```json
156-
"graphql-config.load.legacy": true
157-
```
158-
159-
### Go to definition is not working for my URL
160-
161-
You can try the new experimental `cacheSchemaFileForLookup` option. NOTE: this
162-
will disable all definition lookup for local SDL graphql schema files, and
163-
_only_ perform lookup of the result an SDL result of `graphql-config`
164-
`getSchema()`
165-
166-
To enable, add this to your settings:
167-
168-
```json
169-
"vscode-graphql.cacheSchemaFileForLookup": true,
170-
```
171-
172-
you can also use graphql config if you need to mix and match these settings:
173-
174-
```yml
175-
schema: 'http://myschema.com/graphql'
176-
extensions:
177-
languageService:
178-
cacheSchemaFileForLookup: true
179-
projects:
180-
project1:
181-
schema: 'project1/schema/schema.graphql'
182-
documents: 'project1/queries/**/*.{graphql,tsx,jsx,ts,js}'
183-
extensions:
184-
languageService:
185-
cacheSchemaFileForLookup: false
186-
187-
project2:
188-
schema: 'https://api.spacex.land/graphql/'
189-
documents: 'project2/queries.graphql'
190-
extensions:
191-
endpoints:
192-
default:
193-
url: 'https://api.spacex.land/graphql/'
194-
languageService:
195-
# Do project configs inherit parent config?
196-
cacheSchemaFileForLookup: true
197-
```
198-
199110
### The extension fails with errors about duplicate types
200111

201-
Make sure that you aren't including schema files in the `documents` blob
112+
Your object types must be unique per project (as they must be unique per schema), and your fragment names must also be unique per project.
202113

203114
### The extension fails with errors about missing scalars, directives, etc
204115

@@ -232,6 +143,7 @@ You can search a folder for any of the matching config file names listed above:
232143

233144
```json
234145
"graphql-config.load.rootDir": "./config"
146+
"graphql-config.envFilePath": "./config/.dev.env"
235147
```
236148

237149
Or a specific filepath:
@@ -253,39 +165,15 @@ which would search for `./config/.acmerc`, `.config/.acmerc.js`,
253165
If you have multiple projects, you need to define one top-level config that
254166
defines all project configs using `projects`
255167

256-
### How do I highlight an embedded graphql string?
257-
258-
If you aren't using a template tag function such as `gql` or `graphql`, and just
259-
want to use a plain string, you can use an inline `#graphql` comment:
168+
### How do I enable language features for an embedded graphql string?
260169

261-
```ts
262-
const myQuery = `#graphql
263-
query {
264-
something
265-
}
266-
`;
267-
```
268-
269-
or
270-
271-
```ts
272-
const myQuery =
273-
/* GraphQL */
274-
275-
`
276-
query {
277-
something
278-
}
279-
`;
280-
```
170+
Please refer to the `vscode-graphql-syntax` reference files ([js](https://github.com/graphql/graphiql/blob/main/packages/vscode-graphql-syntax/tests/__fixtures__/test.js),[ts](https://github.com/graphql/graphiql/blob/main/packages/vscode-graphql-syntax/tests/__fixtures__/test.ts),[svelte](https://github.com/graphql/graphiql/blob/main/packages/vscode-graphql-syntax/tests/__fixtures__/test.svelte),[vue](https://github.com/graphql/graphiql/blob/main/packages/vscode-graphql-syntax/tests/__fixtures__/test.vue)) to learn our template tag, comment and other graphql delimiter patterns for the file types that the language server supports. The syntax highlighter currently supports more languages than the language server. If you notice any places where one or the other doesn't work, please report it!
281171

282172
## Known Issues
283173

284-
- the output channel occasionally shows "definition not found" when you first
285-
start the language service, but once the definition cache is built for each
286-
project, definition lookup will work. so if a "peek definition" fails when you
287-
first start the editor or when you first install the extension, just try the
288-
definition lookup again.
174+
- the locally generated schema file for definition lookup currently does not re-generate on schema changes. this will be fixed soon.
175+
- multi-root workspaces support will be added soon as well.
176+
- some graphql-config options aren't always honored, this will also be fixed soon
289177

290178
## Attribution
291179

@@ -312,7 +200,7 @@ This plugin uses the
312200
### Contributing back to this project
313201

314202
This repository is managed by EasyCLA. Project participants must sign the free
315-
([GraphQL Specification Membership agreement](https://preview-spec-membership.graphql.org)
203+
([GraphQL Specification Membership agreement](https://preview-spec-membership.graphql.org))
316204
before making a contribution. You only need to do this one time, and it can be
317205
signed by
318206
[individual contributors](http://individual-spec-membership.graphql.org/) or

0 commit comments

Comments
 (0)