graphql-config

library5.1.6jsnpmunverified

GraphQL Config is the standard configuration layer for GraphQL tools, editors, and IDEs. Current stable version is 5.1.6, with regular releases. It provides a unified way to define schema, documents, and GraphQL-related settings in a single file (YAML, JSON, JS, or TypeScript). It supports multiple loaders (cosmiconfig, TOML) and integrates with GraphQL Code Generator, GraphQL ESLint, and most GraphQL extensions. Unlike ad-hoc config handling, it offers a consistent API for library authors and end-users. Ships TypeScript types. Requires Node >= 16.

development testing

npm install graphql-config

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQL-CONFIG

graphql-config

developmentjavascriptv5.1.6

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

loadConfig

✓ import { loadConfig } from 'graphql-config'

✗ const loadConfig = require('graphql-config').loadConfig

Use named import; ESM-only since v5. CommonJS require is still supported but discouraged.

GraphQLConfig

✓ import type { GraphQLConfig } from 'graphql-config'

✗ import { GraphQLConfig } from 'graphql-config'

GraphQLConfig is a type, use type import in TypeScript to avoid runtime issues.

loadConfigSync

✓ import { loadConfigSync } from 'graphql-config'

✗ const loadConfigSync = require('graphql-config/loadConfigSync')

Synchronous variant available since v5. Use named import from main package, not subpath.

Demonstrates loading a GraphQL config, accessing schema and documents, and retrieving a project schema asynchronously.

import { loadConfig } from 'graphql-config'; async function main() { try { const config = await loadConfig({ rootDir: process.cwd(), configName: 'graphql', // Optionally provide a custom path // configPath: './.graphqlrc.yml', legacy: false, }); console.log('Schema:', config.schema); console.log('Documents:', config.documents); // Example: get project const project = config.getDefault(); if (project) { const schema = await project.getSchema(); console.log('Loaded schema:', schema); } } catch (error) { console.error('Failed to load config:', error); } } main();

Debug

Known issues

breakingVersion 5 drops CommonJS support for Node.js < 16 and ESM is the primary module system.

fix

Update Node.js to >=16 and use import syntax. For CommonJS require, ensure you are using a compatible loader or transpiler.

affects: >=5.0.0

deprecatedThe 'graphql-config/helpers' subpath is deprecated; use 'graphql-config' exports directly.

fix

Replace imports from 'graphql-config/helpers' with imports from 'graphql-config'.

affects: >=5.0.0

gotchaSchema and documents fields can be strings, arrays, or objects. Incorrect type may cause silent failures.

fix

Always validate config shape using TypeScript type GraphQLConfig or runtime checks.

affects: >=3.0.0

gotchaThe 'legacy' option defaults to false in v5; old `.graphqlconfig` files may not be loaded unless legacy is set to true.

fix

Set legacy: true if using the deprecated `.graphqlconfig` format. Prefer `.graphqlrc` or `graphql.config.*`.

affects: >=5.0.0

breakingRemoved support for JSON5 and YAML in cosmiconfig by default; explicit loaders required.

fix

Install 'cosmiconfig-toml-loader' for TOML or ensure your config uses JSON or YAML without custom loaders.

affects: >=5.0.0

Errors

Common errors & fixes

Error: Cannot find module 'graphql-config/loadConfigSync'

Importing a subpath that does not exist in v5.

fix

Use named import from 'graphql-config': import { loadConfigSync } from 'graphql-config'

TypeError: graphql_config_1.loadConfig is not a function

Incorrect default import or require usage.

fix

Use named import: import { loadConfig } from 'graphql-config'; or const { loadConfig } = require('graphql-config');

ConfigError: Config file not found. Tried ...

Config file missing or not named correctly.

fix

Ensure a .graphqlrc file (YAML/JSON/JS/TS) exists in the root directory or specify configPath.

Error: GraphQL Schema validation error: ...

Provided schema URL or file is invalid or points to a non-existent endpoint.

fix

Verify schema field in config: it should be a valid URL, file path, or introspection JSON.

Upgrade

Version history

5.1.6latest on npm

Audit

Dependencies

cosmiconfig-toml-loaderoptionalOptional integration for loading TOML configuration files

graphqlrequiredPeer dependency for schema validation and type system utilities

Agent activity

40 hits · last 30 days

node

Resources

githubhttps://github.com/kamilkisiela/graphql-config ↗

packagegraphql-config ↗

homepagehttps://graphql-config.com ↗