graphql-config gives every GraphQL tool one schema location

The configuration file is two lines and it is the whole contract

The README gives the entire example.

schema: ./schema.json
documents: ./src/components/**/*.jsx

Two keys. The first points at the schema file, the second is a glob for the files that contain GraphQL operations and fragments. That is the whole idea, one configuration for all your GraphQL tools, supported by most tools, editors and IDEs, and the easiest way to configure your development environment with your GraphQL schema.

The value is invisible in a two line example and obvious in a real repository. A typical project has a schema, a set of operation files, and a pile of tools that each want to know where those are. The IDE extension wants the schema to give autocomplete, the linter wants the operations to check them, the code generator wants both to build, the client generator wants the schema to emit types, and a test runner wants the documents to run. Without a shared configuration, each of those is configured separately and they drift.

The repository top level shows that this repository is the specification as much as the implementation. There is a config-schema.json at the root, which is a JSON Schema for the configuration file, plus a .changeset/ directory, a website/ directory, a src/ directory and a test/ directory.

That config-schema.json is the interesting artefact. A JSON Schema for the config file means an editor can validate and autocomplete your graphqlrc as you type it, and it means a tool that wants to support the format has a machine readable description of it rather than prose.

Two audiences, one package

The README describes the project twice, and the two descriptions are for different kinds of consumer.

As a developer, you gain simplicity and a central place to set up libraries, tools and your IDE extensions. That is the end user of the configuration, the person writing the file.

As a library author, GraphQL Config makes it easier to maintain the code responsible for handling configuration, loading GraphQL schemas or even files with GraphQL operations and fragments, and it provides a set of useful methods and an easy-to-work-with API.

That second audience is what makes this a package rather than a documentation page. Every GraphQL tool in the ecosystem needs to answer the same three questions, where is the schema, where are the operations, and how do I handle the environment, and the convention only helps if there is a library that implements the resolution. This is that library, and the tools then depend on it rather than each reimplementing the glob resolution and the environment variable interpolation.

The topics attached to the repository name the tools in that ecosystem. apollo, devtools, relay, intellij and graphql-schema are all listed, and the homepage is the-guild.dev/graphql/config. The GraphQL Hive organisation maintains the repository, and The Guild's Stack contributing guide is where a first-time contributor is pointed.

The package is MIT licensed, and the README points at the website graphql-config.com for the installation and usage documentation rather than duplicating it, which is a reasonable choice for a package whose API surface is documented as prose and types.

The build ships ESM and CommonJS with matching type declarations

The package.json is careful about module format, which is the right way to be for a package that a wide range of tools depend on.

The type field is module, so the package is ESM by default, and the exports map has three branches. The require branch points at the CommonJS build with its own.d.cts typings, the import branch points at the ESM build with its.d.ts typings, and the default branch falls back to the ESM build.

"exports": {
  ".": {
    "require": {
      "types": "./dist/typings/index.d.cts",
      "default": "./dist/cjs/index.js"
    },
    "import": {
      "types": "./dist/typings/index.d.ts",
      "default": "./dist/esm/index.js"
    }
  }
}

The typings field points at dist/typings/index.d.ts, and the typescript field repeats that path for the benefit of tooling that looks for it there. The sideEffects field is false, so the package is tree-shakeable, and the publishConfig sets the publish directory to dist with public access, meaning only the built output is published.

The build is done with bob, and the lifecycle around it is worth reading. The prepublishOnly script runs the build, so a published artefact is always freshly built. The prebuild step cleans the dist directory and regenerates the JSON schema, and the postbuild step runs a script at scripts/postbuild.ts.

The tooling is pnpm based, with packageManager pinned to [email protected] and a pnpm-lock.yaml at the root, and there is a patches/ directory, which means the project patches a dependency rather than forking it. The release flow uses changesets, with a.changeset/ directory and a prerelease script, and there is a CHANGELOG.md for the history.

Tests run twice, against two GraphQL versions

The test scripts are the part of the package.json that says most about how seriously the project takes compatibility, and the script names are the tell.

"test": "vitest .",
"test:once": "vitest . --run",
"test:graphql-16": "vitest . --run --mode graphql-16",
"test:all": "pnpm test:once && pnpm test:graphql-16"

The suite runs under Vitest, and it runs twice: once in the default mode and once in a mode named graphql-16. The mode flag is a Vitest feature, and the naming says what it means, the test suite is exercised against GraphQL version 16 as well as whatever the default is.

That matters because this package sits underneath a large part of the GraphQL toolchain. A tool that loads schemas and operations has to work across the GraphQL versions that the tools using it support, and a config loader that breaks on a version bump breaks every tool that depends on it at once. Running the suite against two versions is a small amount of work that prevents a broad failure.

The test script itself is a watch mode, with test:once as the non-watching variant used in CI through test:all. The vitest configuration is a single vitest.config.ts at the root, and the test/ directory holds the suite.

The linting is set up in a way that reflects a specific constraint. The lint script sets ESLINT_USE_FLAT_CONFIG=false, which forces the legacy eslintrc behaviour, and it uses .gitignore as the ignore path. There is a separate ci:lint script that emits a JSON report to eslint_report.json, which is the shape a CI system wants to consume.

The formatter is Prettier with a cache flag, and husky is present with a .husky/ directory, so the pre-commit hooks are managed rather than being a documented manual step.

Where graphql-config is the wrong choice

The first wrong case is a project with one GraphQL tool and one schema. If you have a single codegen setup and no IDE plugin, the configuration file is one more place to keep the schema path, and the resolution library is a dependency you now maintain for no benefit. The convention earns its cost when the number of tools is greater than one.

The second wrong case is a team that does not control its tools. The package works because the tools in the ecosystem agree to read the configuration. If your tool does not support it, having a graphqlrc does nothing for that tool, and the README's own claim is that it is supported by most tools, which is not the same as all of them. A team running an obscure or internal tool may end up maintaining both the config file and a separate configuration for that tool.

The third wrong case is a project that has outgrown file-based schema loading. graphql-config resolves a schema from a file or a URL and documents from a set of globs. If your schema is assembled at build time from multiple services, or generated into a directory that only exists after a build step, the resolution has to happen after that step and the config file has to point at the output, which is a different workflow from pointing at a checked-in schema.json.

The fourth wrong case is expecting a validation tool. This package resolves configuration, it does not check that your operations match your schema, that is the job of a linter, and the two are separate tools that happen to share a config file.

How it differs from per-tool configuration

The comparison worth making is with the alternative every GraphQL project starts with, which is configuring each tool separately.

That approach looks fine in a small project. The IDE plugin gets a schema path in its own settings, the codegen gets a documents glob in its own config file, the linter gets its own. The cost is not the initial setup, it is the ongoing one. Every time a directory moves or a glob changes, four files have to change together, and the failure is silent in the sense that no tool complains, each one just stops finding what it was looking for. The schema and the operations can end up out of sync, and the symptom is an IDE that has lost autocomplete rather than an error anyone would look for.

graphql-config replaces that with a single source of truth and a resolution layer everyone shares. The difference in approach is that the tools stop owning the resolution logic and start asking a library, which is what makes the drift impossible in principle rather than merely discouraged.

The second difference is what a library author gets. Before this package, a tool that wanted to support the common configuration format had to implement the file discovery, the glob expansion, the environment variable interpolation and the schema loading itself, and every tool did it slightly differently. The package gives them a set of useful methods and an easy-to-work-with API, so a new tool supports the convention by depending on the same resolver the other tools use.

The third difference is the schema for the schema. The config-schema.json means the format is described in a machine readable way, which is what lets an editor validate the file and lets a tool author generate a type definition for it rather than hand-writing one. A convention backed only by prose and an example is a convention that drifts, and this one has a specification artefact behind it.

Editorial conclusion

graphql-config fits a team running more than one GraphQL tool across a monorepo, where schema location and operation globs are otherwise duplicated in half a dozen configuration files, and it fits a library author who needs to resolve a user's schema and documents programmatically rather than parsing a config file by hand. It does not fit a project with one tool and one schema, where the indirection is pure overhead. Before adopting it, check that the tools you use actually read the configuration format, since the package is a convention rather than a mandate, and note that the current release is v5.1.8 from 2026-10-07 with the last push on the same day, and that the package is ESM first with a CommonJS build shipped alongside.

Frequently asked questions

Official sources

1. graphql-hive/graphql-config on GitHub
2. License: MIT
3. Project website
4. README
5. Releases