{"id":10970,"library":"graphql-language-service-server","title":"GraphQL Language Service Server","description":"The GraphQL Language Service Server, currently at version 2.14.8, serves as the backend process for providing rich GraphQL language features within Integrated Development Environments (IDEs). It implements a significant portion of Microsoft's Language Server Protocol (LSP), offering core functionalities such as real-time GraphQL syntax diagnostics, intelligent autocomplete suggestions, and precise hyperlink navigation to fragment definitions and named type declarations. It also provides outline view support for GraphQL queries and facilitates the detection and parsing of GraphQL within template literal tags (e.g., `gql`, `graphql`) across various file types including JavaScript, TypeScript, JSX, TSX, Vue, and Svelte. The package is part of the broader GraphiQL ecosystem, which maintains a consistent release cadence for its components. A key differentiator is its reliance on the `graphql-config` standard for project configuration, enabling robust schema management and multi-project support, although full multi-root workspace support is an ongoing development. This server is the official, specification-compliant backend for GraphQL language tooling.","status":"active","version":"2.14.8","language":"javascript","source_language":"en","source_url":"https://github.com/graphql/graphiql","tags":["javascript","graphql","language server","LSP","vue","svelte","typescript"],"install":[{"cmd":"npm install graphql-language-service-server","lang":"bash","label":"npm"},{"cmd":"yarn add graphql-language-service-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add graphql-language-service-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for GraphQL schema and language parsing.","package":"graphql","optional":false},{"reason":"Required for configuring GraphQL projects, schemas, and documents for the language server. Not a direct `package.json` dependency but critical for operation.","package":"graphql-config","optional":false}],"imports":[{"note":"The library primarily uses ES modules. Use `import` syntax. Requires Node.js ES module support or a transpilation step.","wrong":"const { startServer } = require('graphql-language-service-server');","symbol":"startServer","correct":"import { startServer } from 'graphql-language-service-server';"},{"note":"The `startServer` function is asynchronous and returns a Promise. Always `await` its call.","symbol":"startServer","correct":"await startServer({ method: 'node' });"}],"quickstart":{"code":"import { startServer } from 'graphql-language-service-server';\nimport { loadConfig } from 'graphql-config'; // Ensure 'graphql-config' is installed\n\nasync function initializeLanguageServer() {\n  // A graphql.config.js, .graphqlrc.yml, etc. is required in your project root.\n  // Example graphql.config.js:\n  // module.exports = {\n  //   schema: './schema.graphql',\n  //   documents: './src/**/*.graphql',\n  //   extensions: {\n  //     endpoints: {\n  //       default: {\n  //         url: 'http://localhost:4000/graphql',\n  //         headers: {\n  //           Authorization: `Bearer ${process.env.GRAPHQL_TOKEN || ''}`,\n  //         },\n  //       },\n  //     },\n  //   },\n  // };\n\n  const config = await loadConfig();\n\n  if (!config) {\n    console.error('Error: A graphql-config file (.graphqlrc.yml, graphql.config.js, etc.) is required in your project.');\n    process.exit(1);\n  }\n\n  console.log('Starting GraphQL Language Service Server via IPC (Node.js method)...');\n  // 'method: \"node\"' uses Node.js IPC (stdin/stdout) for communication with the LSP client.\n  // Other methods include 'socket' and 'streams'.\n  await startServer({\n    method: 'node',\n    // You can pass the loaded config directly if needed, but the server\n    // typically discovers it automatically based on the 'configDir'.\n    // config,\n    // configDir: process.cwd(),\n  });\n  console.log('GraphQL Language Service Server successfully started. Waiting for LSP client messages.');\n}\n\ninitializeLanguageServer().catch(error => {\n  console.error('Failed to initialize GraphQL Language Service Server:', error);\n  process.exit(1);\n});","lang":"typescript","description":"This quickstart demonstrates how to programmatically start the GraphQL Language Service Server. It initializes the server using Node.js IPC for communication and highlights the essential `graphql-config` setup required for operation."},"warnings":[{"fix":"Create a `graphql-config` file in your project root or specify its path via server options.","message":"A `graphql-config` file (e.g., `.graphqlrc.yml`, `graphql.config.js`) is mandatory for the language server to function correctly. Without it, the server cannot determine your schema, documents, or project settings.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Ensure your Node.js environment meets the specified version requirements. Update Node.js if necessary.","message":"The server requires Node.js version `^18.18.0` or `>=20.9.0` for full compatibility and optimal performance. Older Node.js versions may encounter errors or unexpected behavior.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"After modifying configuration files, restart your editor or the LSP server process.","message":"Changes to your `graphql-config` file or other relevant project settings may not immediately be picked up by a running language server. You might need to restart your IDE or the language server process manually for changes to take effect.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Organize your projects to use a single `graphql-config` file for the entire workspace or open distinct project folders separately until multi-root support is implemented.","message":"While `graphql-config` supports multi-project setups, the GraphQL Language Service Server does not yet fully support multi-root workspaces within IDEs like VS Code. This can lead to unexpected behavior when dealing with multiple distinct project roots in a single editor instance.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure your Node.js project is configured for ES modules (`\"type\": \"module\"` in `package.json`) or use a transpiler like Babel/TypeScript to convert `import` to `require` for CommonJS environments.","cause":"Attempting to use ES module `import` syntax in a CommonJS (`.js` without `\"type\": \"module\"` in `package.json`, or a `.cjs` file) context.","error":"Cannot use import statement outside of a module"},{"fix":"Create a valid `graphql-config` file (e.g., `.graphqlrc.yml`, `graphql.config.js`) in your project's root directory or the directory where the server is expected to operate.","cause":"The language server failed to find or load a `graphql-config` file in the expected locations.","error":"Error: A graphql-config file (.graphqlrc.yml, graphql.config.js, etc.) is required in your project."},{"fix":"Check the server's standard error output for more specific messages. Verify Node.js version, `graphql-config` validity, and ensure all peer dependencies are installed. Debug the server process if running manually.","cause":"A generic error indicating a failure in the Language Server Protocol (LSP) communication or an issue within the `graphql-language-service-server` process itself, often seen in LSP client logs.","error":"[ERROR] .../vim/lsp/rpc.lua:430 \"rpc\" \"graphql-lsp\" \"stderr\" '... graphql-language-service'"}],"ecosystem":"npm"}