Configuration File

GraphQL Analyzer uses the standard .graphqlrc configuration format, compatible with tools like GraphQL Code Generator and GraphQL ESLint.

File format

YAML, JSON, and TOML are supported. JavaScript/TypeScript configs (graphql.config.js, graphql.config.ts) are not supported.

File discovery

The tool searches for these files in order, walking up the directory tree from your project root:

1. .graphqlrc.yml / .graphqlrc.yaml
2. .graphqlrc.json
3. .graphqlrc.toml
4. .graphqlrc (YAML or JSON, auto-detected)
5. graphql.config.yml / graphql.config.yaml
6. graphql.config.json
7. graphql.config.toml
8. package.json (with a "graphql" key — lowest priority fallback)

You can also specify a config file explicitly:

graphql --config path/to/.graphqlrc.yml validate

Basic configuration

YAML

.graphqlrc.yml

schema: "schema.graphql"
documents: "src/**/*.{graphql,ts,tsx}"

TOML

.graphqlrc.toml

schema = "schema.graphql"
documents = "src/**/*.{graphql,ts,tsx}"

JSON

{
  "schema": "schema.graphql",
  "documents": "src/**/*.{graphql,ts,tsx}"
}

Field	Required	Description
schema	Yes	Schema source (file, glob, or URL)
documents	No	Document file patterns
include	No	File patterns that scope which files belong to this project
exclude	No	File patterns to exclude from this project

Adding linting

YAML

schema: "schema.graphql"
documents: "src/**/*.{graphql,ts,tsx}"

extensions:
  graphql-analyzer:
    lint:
      extends: recommended
      rules:
        noDeprecated: warn

TOML

schema = "schema.graphql"
documents = "src/**/*.{graphql,ts,tsx}"

[extensions.graphql-analyzer.lint]
extends = "recommended"

[extensions.graphql-analyzer.lint.rules]
noDeprecated = "warn"

See Linting Configuration for details.

Multi-project setup

For monorepos or projects with multiple GraphQL schemas:

YAML

projects:
  api:
    schema: api/schema.graphql
    documents: api/**/*.graphql
  client:
    schema: client/schema.graphql
    documents: client/**/*.{graphql,tsx}

TOML

[projects.api]
schema = "api/schema.graphql"
documents = "api/**/*.graphql"

[projects.client]
schema = "client/schema.graphql"
documents = "client/**/*.{graphql,tsx}"

See Multi-Project Workspaces for details.

Migrating from JavaScript config

If you have a graphql.config.js or graphql.config.ts, convert it to YAML, JSON, or TOML.

For configs that are already plain objects, the translation is mechanical:

// graphql.config.js (NOT SUPPORTED)
module.exports = {
  schema: "schema.graphql",
  documents: "src/**/*.graphql",
};

# .graphqlrc.yml (equivalent)
schema: "schema.graphql"
documents: "src/**/*.graphql"

One-liner conversion

If your config is a static object (or evaluates to one), dump it to JSON with a single command. .graphqlrc.json is supported directly — no further conversion required.

node -e "import('./graphql.config.js').then(c => console.log(JSON.stringify(c.default ?? c, null, 2)))" > .graphqlrc.json

The dynamic import() returns a promise resolving to the namespace object, which .then(c => …) unwraps. c.default ?? c picks the ESM default export when present, otherwise falls back to the CJS exports object — so the same command handles both module.exports = … and export default ….

For TypeScript configs, point at graphql.config.ts instead. Modern Node strips type annotations natively (Node 22.6+ with --experimental-strip-types, or Node 23.6+ where it’s on by default), so no separate runner like tsx is needed.

If you’d prefer YAML, pipe the JSON through any YAML converter — for example, with js-yaml installed:

node -e "console.log(require('js-yaml').dump(require('./.graphqlrc.json')))" > .graphqlrc.yml && rm .graphqlrc.json

What won’t carry over

graphql.config.js is loaded by cosmiconfig, which evaluates the JavaScript at load time. That means JS configs can express things a static YAML/JSON/TOML file cannot. GraphQL Analyzer does not support any of the following:

Unsupported in static configs

• Function-valued fields anywhere in the tree — common cases include HTTP Authorization headers built by a function for dynamic auth tokens, or extensions.codegen.hooks.afterAllFileWrite set to a function (only string shell commands carry over). Function values silently disappear from JSON.stringify(), so the one-liner produces an incomplete config rather than erroring — easy to miss.
• process.env interpolation via JS — e.g. headers.Authorization built from a template literal embedding process.env.TOKEN. Use the static ${TOKEN} interpolation described below instead — it’s resolved when the YAML/JSON is loaded, not baked into the file.
• Conditional branches on runtime state — e.g. switching documents globs or projects based on process.env.CI or NODE_ENV.
• Spread-imported config fragments — e.g. spreading the result of require("./shared-globs") into the documents array.
• Custom loaders, transforms, or plugins registered in JS — e.g. graphql-config v5’s top-level loaders: [new UrlLoader()], or codegen plugins referenced via require().

If your existing config uses any of these, you’ll need to address them before migrating.

Workarounds for dynamic needs

Most real-world dynamic configs fall into one of two buckets, and both have static equivalents:

• Secrets, tokens, and per-environment URLs → use environment variable interpolation. ${API_TOKEN} and ${TENANT_ID:default-tenant} cover the common cases without any JavaScript.
• Anything else dynamic (computed schemas, conditional projects, generated globs) → generate the config file as a build step. Have your existing JavaScript write a .graphqlrc.yml or .graphqlrc.json to disk before invoking GraphQL Analyzer; treat the generated file as a build artifact.

Environment variable interpolation

Config values support ${VAR} and ${VAR:default} substitution. This is useful for keeping secrets like API tokens out of your config file:

schema:
  url: https://api.example.com/graphql
  headers:
    Authorization: Bearer ${API_TOKEN}
    X-Tenant: ${TENANT_ID:default-tenant}

• ${VAR} — replaced with the value of VAR; fails with an error if the variable is unset
• ${VAR:default} — replaced with the value of VAR, or default if the variable is unset

Interpolation is applied to all string values before the config is parsed, so it works in any field — URLs, headers, file paths, etc.

Environment variables

Variable	Description
RUST_LOG	Set log level for debugging