Make loadConfigOptions
default plugins to use with babel parser
default extensions to use when parsing for GraphQL strings any changes should also be reflected in vscode-graphql-syntax textmate grammar & package.json
.graphql is the officially recommended extension for graphql files
.gql and .graphqls are included for compatibility for commonly used extensions
GQL is a registered trademark of Google, and refers to Google Query Language. GraphQL Foundation does not recommend using this extension or acronym for referring to GraphQL.
any changes should also be reflected in vscode-graphql-syntax textmate grammar & package.json
take the resultant message connection, and attach the matching MessageProcessor
instance event handlers
similar to languageFeatures.ts in monaco language modes
Legacy mappings for < 2.5.0
Helper functions to perform requested services from client/server.
startServer - initialize LSP server with options
server initialization methods
Copyright (c) 2021 GraphQL Contributors All rights reserved.
This source code is licensed under the license found in the LICENSE file in the root directory of this source tree.
default tag delimiters to use when parsing GraphQL strings (for js/ts/vue/svelte) any changes should also be reflected in vscode-graphql-syntax textmate grammar
Generated using TypeDoc
graphql-language-service-server
Changelog | API Docs | Discord Channel
Server process backing the GraphQL Language Service.
GraphQL Language Service Server provides an interface for building GraphQL language services for IDEs.
Partial support for Microsoft's Language Server Protocol is in place, with more to come in the future.
Supported features include:
gql
graphql
and other template tags inside javascript, typescript, jsx, ts, vue and svelte files, and an interface to allow custom parsing of all files.Installation and Usage
Dependencies
^18.18.0 || >=20.9.0
or later is required.Installation
npm install graphql-language-service-server # or yarn add graphql-language-service-server
We also provide a CLI interface to this server, see
graphql-language-service-cli
Usage
Initialize the GraphQL Language Server with the
startServer
function:import { startServer } from 'graphql-language-service-server'; await startServer({ method: 'node', });
If you are developing a service or extension, this is the LSP language server you want to run.
When developing vscode extensions, just the above is enough to get started for your extension's
ServerOptions.run.module
, for example.startServer
function takes the following parameters:true
when method issocket
,false
otherwisefalse
socket
,streams
, ornode
(ipc)false
graphql-config
instance fromloadConfig
(see example above)false
false
false
parseDocument
functionfalse
. defaults to['.js', '.ts', '.tsx, '.jsx']
GraphQL configuration file
You must provide a graphql config file
Check out graphql-config to learn the many ways you can define your graphql config
.graphqlrc
or.graphqlrc.yml/yaml
orgraphql.config.yml
schema: 'packages/api/src/schema.graphql' documents: 'packages/app/src/components/**/*.{tsx,ts}' extensions: endpoints: example: url: 'http://localhost:8000' customExtension: foo: true
.graphqlrc
or.graphqlrc.json
orgraphql.config.json
{ "schema": "https://localhost:8000" }
graphql.config.js
or.graphqlrc.js
module.exports = { schema: 'https://localhost:8000' };
custom
startServer
use graphql config
loadConfig
for further customization:import { loadConfig } from 'graphql-config'; // 3.0.0 or later! // with required params const config = await loadConfig(); await startServer({ method: 'node', // or instead of configName, an exact path (relative from rootDir or absolute) // deprecated for: loadConfigOptions.rootDir. root directory for graphql config file(s), or for relative resolution for exact `filePath`. default process.cwd() // configDir: '', loadConfigOptions: { // any of the options for graphql-config@3 `loadConfig()` schema: await config.getSchema(), // rootDir is same as `configDir` before, the path where the graphql config file would be found by cosmic-config rootDir: 'config/', // or - the relative or absolute path to your file filePath: 'exact/path/to/config.js', // (also supports yml, json, ts, toml) // myPlatform.config.js/json/yaml works now! configName: 'myPlatform', }, });
Custom
graphql-config
featuresThe graphql-config features we support are:
module.exports = { extensions: { // add customDirectives (legacy). you can now provide multiple schema pointers to config.schema/project.schema, including inline strings. same with scalars or any SDL type that you'd like to append to the schema customDirectives: ['@myExampleDirective'], // a function that returns an array of validation rules, ala https://github.com/graphql/graphql-js/tree/main/src/validation/rules // note that this file will be loaded by the vscode runtime, so the node version and other factors will come into play customValidationRules: require('./config/customValidationRules'), schemaCacheTTL: 1000, // reduce or increase minimum schema cache lifetime from 30000ms (30 seconds). you may want to reduce this if you are developing fullstack with network schema languageService: { // this is enabled by default if non-local files are specified in the project `schema` // NOTE: this will disable all definition lookup for local SDL files cacheSchemaFileForLookup: true, // 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" enableValidation: true, // (experimental) enhanced auto expansion of graphql leaf fields and arguments fillLeafsOnComplete: true, // instead of jumping directly to the SDL file, you can override definition peek/jump results to point to different files or locations // (for example, source files for your schema in any language!) // based on Relay vscode's pathToLocateCommand // see LocateCommand type! locateCommand(projectName, typePath, info) { // pass more info, such as GraphQLType with the ast node. info.project is also available if you need it const { path, range } = ourLookupUtility( projectName, typePath, info.type.node, ); return { uri: path, range }; // range.start.line/range.end.character/etc, base 1 // you can also return relay LSP style // return '/path/to/file.py:20:23'; // (range: 20:1 ) // return '/path/to/file.py'; // (range: 1:1 1:1) }, }, }, };
or for multi-project workspaces:
// graphql.config.ts export default { projects: { myProject: { schema: [ // internally in `graphql-config`, an attempt will be made to combine these schemas into one in-memory schema to use for validation, lookup, etc 'http://localhost:8080', './my-project/schema.graphql', './my-project/schema.ts', '@customDirective(arg: String!)', 'scalar CustomScalar', ], // project specific defaults extensions: { languageService: { cacheSchemaFileForLookup: true, enableValidation: false, }, }, }, anotherProject: { schema: { 'http://localhost:8081': { customHeaders: { Authorization: 'Bearer example' }, }, }, }, }, // global defaults for all projects extensions: { languageService: { cacheSchemaFileForLookup: false, enableValidation: true, }, }, };
You can specify any of these settings globally as above, or per project. Read the graphql-config docs to learn more about this!
For secrets (headers, urls, etc), you can import
dotenv()
and set a base path as you wish in yourgraphql-config
file to pre-loadprocess.env
variables.Troubleshooting notes
Workspace Configuration
The LSP Server reads config by sending
workspace/configuration
method when it initializes.Note: We still do not support LSP multi-root workspaces but will tackle this very soon!
Many LSP clients beyond vscode offer ways to set these configurations, such as via
initializationOptions
in nvim.coc. The options are mostly designed to configure graphql-config's load parameters, the only thing we can't configure with graphql config. The final option can be set ingraphql-config
as wellgraphql-config.load.baseDir
graphql-config.load.filepath
null
graphql-config.load.configName
graphql
graphql
graphql-config.load.legacy
true
graphql-config@2
graphql-config.dotEnvPath
null
graphql-config@2
vscode-graphql.cacheSchemaFileForLookup
true
ifschema
contains non-SDL files or URLsschema
config are URLs or introspection JSON, or if you have any non-local SDL files inschema
vscode-graphql.schemaCacheTTL
30000
vscode-graphql.debug
false
all the
graphql-config.load.*
configuration values come from staticloadConfig()
options in graphql config.(more coming soon!)
Architectural Overview
GraphQL Language Service currently communicates via Stream transport with the IDE server. GraphQL server will receive/send RPC messages to perform language service features, while caching the necessary GraphQL artifacts such as fragment definitions, GraphQL schemas etc. More about the server interface and RPC message format below.
The IDE server should launch a separate GraphQL server with its own child process for each
.graphqlrc.yml
file the IDE finds (using the nearest ancestor directory relative to the file currently being edited):./application ./productA .graphqlrc.yml ProductAQuery.graphql ProductASchema.graphql ./productB .graphqlrc.yml ProductBQuery.graphql ProductBSchema.graphql
A separate GraphQL server should be instantiated for
ProductA
andProductB
, each with its own.graphqlrc.yml
file, as illustrated in the directory structure above.The IDE server should manage the lifecycle of the GraphQL server. Ideally, the IDE server should spawn a child process for each of the GraphQL Language Service processes necessary, and gracefully exit the processes as the IDE closes. In case of errors or a sudden halt the GraphQL Language Service will close as the stream from the IDE closes.
Server Interface
GraphQL Language Server uses JSON-RPC to communicate with the IDE servers. Microsoft's language server currently supports two communication transports: Stream (stdio) and IPC. For IPC transport, the reference guide to be used for development is the language server protocol documentation.
For each transport, there is a slight difference in JSON message format, especially in how the methods to be invoked are defined - below are the currently supported methods for each transport (will be updated as progress is made):
getDiagnostics
textDocument/publishDiagnostics
getAutocompleteSuggestions
textDocument/completion
getOutline
textDocument/outline
getDocumentSymbols
textDocument/symbols
getWorkspaceSymbols
workspace/symbols
getDefinition
textDocument/definition
getWorkspaceDefinition
workspace/definition
didOpen/didClose/didSave/didChange
events