GraphQL Language Service Server

Common errors

• Cannot use import statement outside of a module

  cause Attempting to use ES module `import` syntax in a CommonJS (`.js` without `"type": "module"` in `package.json`, or a `.cjs` file) context.
  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.

• Error: A graphql-config file (.graphqlrc.yml, graphql.config.js, etc.) is required in your project.

  cause The language server failed to find or load a `graphql-config` file in the expected locations.
  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.

• [ERROR] .../vim/lsp/rpc.lua:430 "rpc" "graphql-lsp" "stderr" '... graphql-language-service'

  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.
  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.

Warnings

• gotcha 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.
  Fix: Create a `graphql-config` file in your project root or specify its path via server options.
• breaking 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.
  Fix: Ensure your Node.js environment meets the specified version requirements. Update Node.js if necessary.
• gotcha 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.
  Fix: After modifying configuration files, restart your editor or the LSP server process.
• gotcha 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.
  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.

Install

• npm install graphql-language-service-server npm
• yarn add graphql-language-service-server yarn
• pnpm add graphql-language-service-server pnpm

Imports

• startServer
  wrong:

  const { startServer } = require('graphql-language-service-server');

  correct:

  import { startServer } from 'graphql-language-service-server';

  The library primarily uses ES modules. Use `import` syntax. Requires Node.js ES module support or a transpilation step.
• startServer

  await startServer({ method: 'node' });

  The `startServer` function is asynchronous and returns a Promise. Always `await` its call.

Quickstart

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.

import { startServer } from 'graphql-language-service-server';
import { loadConfig } from 'graphql-config'; // Ensure 'graphql-config' is installed

async function initializeLanguageServer() {
  // A graphql.config.js, .graphqlrc.yml, etc. is required in your project root.
  // Example graphql.config.js:
  // module.exports = {
  //   schema: './schema.graphql',
  //   documents: './src/**/*.graphql',
  //   extensions: {
  //     endpoints: {
  //       default: {
  //         url: 'http://localhost:4000/graphql',
  //         headers: {
  //           Authorization: `Bearer ${process.env.GRAPHQL_TOKEN || ''}`,
  //         },
  //       },
  //     },
  //   },
  // };

  const config = await loadConfig();

  if (!config) {
    console.error('Error: A graphql-config file (.graphqlrc.yml, graphql.config.js, etc.) is required in your project.');
    process.exit(1);
  }

  console.log('Starting GraphQL Language Service Server via IPC (Node.js method)...');
  // 'method: "node"' uses Node.js IPC (stdin/stdout) for communication with the LSP client.
  // Other methods include 'socket' and 'streams'.
  await startServer({
    method: 'node',
    // You can pass the loaded config directly if needed, but the server
    // typically discovers it automatically based on the 'configDir'.
    // config,
    // configDir: process.cwd(),
  });
  console.log('GraphQL Language Service Server successfully started. Waiting for LSP client messages.');
}

initializeLanguageServer().catch(error => {
  console.error('Failed to initialize GraphQL Language Service Server:', error);
  process.exit(1);
});