Changelog
| Discord Channel |
LSP Server Docs
GraphQL extension for VSCode built with the aim to tightly integrate the GraphQL
Ecosystem with VSCode for an awesome developer experience.
![](https://camo.githubusercontent.com/97dc1080d5e6883c4eec3eaa6b7d0f29802e6b4b/687474703a2f2f672e7265636f726469742e636f2f497379504655484e5a342e676966)
.graphql
, .gql
file extension support and gql
/graphql
tagged template literal support for tsx, jsx, ts, js
- syntax highlighting (provided by
vscode-graphql-syntax
)
- autocomplete suggestions
- validation against schema
- snippets (interface, type, input, enum, union)
- hover support
- go to definition support (input, enum, type)
- outline support
Getting Started
This extension requires a graphql-config file.
To support language features like completion and "go-to definition" across multiple files,
please include documents
in the graphql-config
file default or per-project
Simplest Config Example
# .graphqlrc.yml or graphql.config.yml
schema: 'schema.graphql'
documents: 'src/**/*.{graphql,js,ts,jsx,tsx}'
package.json
:
"graphql": {
"schema": "https://localhost:3001",
"documents": "**/*.{graphql,js,ts,jsx,tsx}"
},
// .graphqlrc.ts or graphql.config.ts
export default {
schema: 'schema.graphql',
documents: '**/*.{graphql,js,ts,jsx,tsx}',
};
same for .json, .toml, etc
Additional Features
- Loads the LSP server upon detecting a
graphql-config
file at root level or in a
parent level directory, or a package.json
file with graphql
config
- Loads
.graphql
, .gql
files, and detects gql
, graphql
tags and /** GraphQL */
and #graphql
comments in js, ts, jsx, tsx, vue files
- pre-load schema and fragment definitions
- Support
graphql-config
files with one project
and multiple projects (multi-workspace roots with multiple graphql config
files not yet supported)
- the language service re-starts on saved changes to vscode settings and/or
graphql config!
Configuration Examples
For more help with configuring the language server,
the language server readme
is the source of truth for all settings used by all editors which use the
language server.
This includes LSP settings provided by extensions like vscode-graphql
, nvim, etc.
There are a number of configurations that can be provided from both editor settings or the graphql config file, and the editor setting takes precedence, to allow users to override their graphql config file settings in a user context as needed.
The graphql-config
docs are also very helpful for the config file.
Advanced Example
Multi-project can be used for both local files, URL defined schema, or both
import dotenv from 'dotenv';
dotenv.config();
// .graphqlrc.ts or graphql.config.ts
export default {
projects: {
app: {
schema: ['src/schema.graphql', 'directives.graphql'],
documents: ['**/*.{graphql,js,ts,jsx,tsx}', 'my/fragments.graphql'],
},
db: {
schema: 'src/generated/db.graphql',
documents: ['src/db/**/*.graphql', 'my/fragments.graphql'],
extensions: {
// for use with `vscode-graphql-execution`, for example:
endpoints: {
default: {
url: 'https://localhost:3001/graphql/',
headers: {
Authorization: `Bearer ${process.env.API_TOKEN}`,
},
},
},
},
},
},
};
Notice that documents
key supports glob pattern and hence ["**/*.graphql"]
is also valid.
Frequently Asked Questions
The extension fails with errors about duplicate types
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.
The extension fails with errors about missing scalars, directives, etc
Make sure that your schema
pointers refer to a complete schema!
In JSX and TSX files I see completion items I don't need
The way vscode lets you filter these out is
on the user end
So you'll need to add something like this to your global vscode settings:
"[typescriptreact]": {
"editor.suggest.filteredTypes": {
"snippet": false
}
},
"[javascriptreact]": {
"editor.suggest.filteredTypes": {
"snippet": false
}
}
My graphql config file is not at the root
Good news, we have configs for this now!
You can search a folder for any of the matching config file names listed above:
"graphql-config.load.rootDir": "./config"
"graphql-config.envFilePath": "./config/.dev.env"
Or a specific filepath:
"graphql-config.load.filePath": "./config/my-graphql-config.js"
Or a different configName
that allows different formats:
"graphql-config.load.rootDir": "./config",
"graphql-config.load.configName": "acme"
which would search for ./config/.acmerc
, .config/.acmerc.js
,
.config/acme.config.json
, etc matching the config paths above
If you have multiple projects, you need to define one top-level config that
defines all project configs using projects
How do I enable language features for an embedded graphql string?
Please refer to the vscode-graphql-syntax
reference files (js,ts,svelte,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!
Known Issues
- the locally generated schema file for definition lookup currently does not re-generate on schema changes. this will be fixed soon.
- multi-root workspaces support will be added soon as well.
- some graphql-config options aren't always honored, this will also be fixed soon
Attribution
Thanks to apollo for their
graphql-vscode grammars!
We have borrowed from these on several occasions. If you are looking for the
most replete set of vscode grammars for writing your own extension, look no
further!
Development
This plugin uses the
GraphQL language server
- Clone the repository - https://github.com/graphql/graphiql
yarn
- Run "VScode Extension" launcher in vscode
- This will open another VSCode instance with extension enabled
- Open a project with a graphql config file - ":electric_plug: graphql" in
VSCode status bar indicates that the extension is in use
- Logs for GraphQL language service will appear in output section under
GraphQL Language Service
Contributing back to this project
This repository is managed by EasyCLA. Project participants must sign the free
(GraphQL Specification Membership agreement)
before making a contribution. You only need to do this one time, and it can be
signed by
individual contributors or
their employers.
To initiate the signature process please open a PR against this repo. The
EasyCLA bot will block the merge if we still need a membership agreement from
you.
You can find
detailed information here.
If you have issues, please email
operations@graphql.org.
If your company benefits from GraphQL and you would like to provide essential
financial support for the systems and people that power our community, please
also consider membership in the
GraphQL Foundation.
License
MIT