Multi-project graphql-config for the LSP: schema, documents, include, exclude, and fast startup

[unrevised6419]

I spent some time getting the GraphQL language server (vscode-graphql 0.13.x / graphql-language-service-server 2.15.0, graphql-config 5.1.6) to behave in a pnpm monorepo with three schemas. Sharing what I learned, because the interplay between schema, documents, include and exclude is not obvious, and one setting turned a ~15 s startup into an almost instant one.

The setup

Three projects, each with its own schema and its own document suffix (*.api.gql, *.cms.gql, *.crm.gql). GraphQL also appears in .ts files that the LSP should ignore (they are handled by other tooling).

What each key actually does

graphql-config decides which project a file belongs to with GraphQLProjectConfig.match():

match(filepath) {
  if ([this.schema, this.documents].some(p => match(filepath, this.dirpath, p))) return true;
  if (this.exclude && match(filepath, this.dirpath, this.exclude)) return false;
  return this.include ? match(filepath, this.dirpath, this.include) : false;
}

and GraphQLConfig.getProjectForFile() falls back to the first project that has neither include nor exclude when nothing matches.

• documents: the files the LSP pre-loads at startup. Fragment definitions are only indexed from here, so without it you get Unknown fragment "X" for fragments defined in other files.
• schema: also counts as "belongs to this project".
• include / exclude: only affect project membership; they never load anything. exclude is additionally used as the glob ignore list when loading documents.
• Having any include or exclude on a project removes it from the fallback. That is the switch that stops the LSP from validating .ts files that are not part of documents (see [lsp-server] 🐞 JS/TS files should only be checked when included in documents config glob #3588).

The config that works

import path from "node:path";
import { schemaPaths } from "@repo/graphql-config/shared"; // absolute paths

// graphql-config matching only works with pointers relative to the config dir
const rel = (p) => path.relative(import.meta.dirname, p);

const exclude = ["**/node_modules/**", "**/dist/**", "**/generated/**", "**/coverage/**"];

export default {
  projects: {
    api: { schema: rel(schemaPaths.api), documents: "**/*.api.gql", include: "**/*.api.gql", exclude },
    cms: { schema: rel(schemaPaths.cms), documents: "**/*.cms.gql", include: "**/*.cms.gql", exclude },
    crm: { schema: rel(schemaPaths.crm), documents: "**/*.crm.gql", include: "**/*.crm.gql", exclude },
  },
};

Notes:

1. schema must be relative to the config file. An absolute path loads the schema fine, but never matches in match(), so the schema files end up in no project (File '.../api.schema.graphql' doesn't match any project in the output). Without include/exclude the fallback hides this, and assigns all schema files to the first project.
2. Keep documents and include both. include alone breaks fragment lookup; documents alone keeps the fallback and validates every .ts file.
3. Expect one log line per non-GraphQL file you open: there was an error loading the project config for this file ... doesn't match any project. It is harmless; the file is simply skipped (LSP Server: No Errors on mismatched file #2498).

Startup speed: exclude node_modules

The LSP loads documents through graphql-tools, which does not ignore node_modules by default. A root-level glob like **/*.api.gql therefore walks the whole pnpm store, once per project. Measured in our repo (warm FS cache, same 32/13/7 files found in every case):

exclude	Document glob time (3 projects)
none	~1.2 s per project
**/node_modules/**	263 ms
+ **/dist/**, **/generated/**, **/coverage/**	106 ms

Cold, the unexcluded case took ~15 s before GraphQL Language Server caches initialized showed up, and go-to-definition did nothing until then. With the exclude list startup is effectively instant.

Dot-directories (.next, .nx, .git) are already skipped, since the glob does not match dot paths by default. So the useful additions are build outputs (dist, build, coverage, generated code) that live in regular directories.

Do not put the excludes in documents as !**/node_modules/**: negated globs in documents make match() return true for every file outside node_modules, which brings back the .ts validation. Use exclude.

Related issues

• [lsp-server] 🐞 JS/TS files should only be checked when included in documents config glob #3588: .ts files validated through the fallback project
• LSP Server: No Errors on mismatched file #2498: "doesn't match any project" logged as an error
• match() never matches absolute schema/documents/include/exclude pointers graphql-hive/graphql-config#1795: absolute pointers never match in match()
• [lsp-server] 🐞 didClose handler is not bound and throws on every file close #4612: didClose handler not bound
• [lsp-server] 🐞 Cache initialization runs several times in parallel during startup #4613: cache initialization runs several times in parallel during startup
• [lsp-server] 🐞 documents scan does not skip node_modules, slow startup in monorepos #4614: documents scan does not skip node_modules
• [lsp-server] 🐞 _cacheSchemaFile drops the project, schema files are looked up again #4615: _cacheSchemaFile drops the project

[unrevised6419]

Correction to the "Startup speed" section: dot directories are not skipped by the scan. The glob never matches files under them, but it still walks into them, and it follows symlinks while doing so.

It turned up through git worktrees. Claude Code (and similar agent tools) create them inside the repo, at .claude/worktrees/<name>/. Each is a full checkout with its own node_modules plus other symlinks into the global pnpm store (virtualStoreType: global). Symlinks not named node_modules slip past **/node_modules/**, so the walk followed them into ~/Library/pnpm/store/v11/links/..., i.e. every package installed on the machine.

Measured with graphql-config 5.1.7 project.getDocuments(), two worktrees present, same documents found in both runs, none from .claude:

exclude	Time per project
**/node_modules/**, **/dist/**, **/generated/**, **/coverage/**	16–22 s
+ .claude/worktrees/**	62–241 ms

In the editor this showed up as the language server pinned at ~350% CPU and no autocomplete until the scan finished. Adding the worktree directory to exclude fixed it straight away:

const exclude = [
  "**/node_modules/**",
  "**/dist/**",
  "**/generated/**",
  "**/coverage/**",
  ".claude/worktrees/**",
];

So exclude any directory inside the repo that holds whole checkouts or store symlinks (agent worktrees, git worktree add targets), dot-prefixed or not.

Drafted by AI, reviewed by me.