{"id":47845,"library":"graphql-config","title":"GraphQL Config","description":"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.","status":"active","version":"5.1.6","language":"javascript","source_language":"en","source_url":"https://github.com/kamilkisiela/graphql-config","tags":["javascript","graphql","config","relay","apollo","typescript"],"install":[{"cmd":"npm install graphql-config","lang":"bash","label":"npm"},{"cmd":"yarn add graphql-config","lang":"bash","label":"yarn"},{"cmd":"pnpm add graphql-config","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Optional integration for loading TOML configuration files","package":"cosmiconfig-toml-loader","optional":true},{"reason":"Peer dependency for schema validation and type system utilities","package":"graphql","optional":false}],"imports":[{"note":"Use named import; ESM-only since v5. CommonJS require is still supported but discouraged.","wrong":"const loadConfig = require('graphql-config').loadConfig","symbol":"loadConfig","correct":"import { loadConfig } from 'graphql-config'"},{"note":"GraphQLConfig is a type, use type import in TypeScript to avoid runtime issues.","wrong":"import { GraphQLConfig } from 'graphql-config'","symbol":"GraphQLConfig","correct":"import type { GraphQLConfig } from 'graphql-config'"},{"note":"Synchronous variant available since v5. Use named import from main package, not subpath.","wrong":"const loadConfigSync = require('graphql-config/loadConfigSync')","symbol":"loadConfigSync","correct":"import { loadConfigSync } from 'graphql-config'"}],"quickstart":{"code":"import { loadConfig } from 'graphql-config';\n\nasync function main() {\n  try {\n    const config = await loadConfig({\n      rootDir: process.cwd(),\n      configName: 'graphql',\n      // Optionally provide a custom path\n      // configPath: './.graphqlrc.yml',\n      legacy: false,\n    });\n\n    console.log('Schema:', config.schema);\n    console.log('Documents:', config.documents);\n\n    // Example: get project\n    const project = config.getDefault();\n    if (project) {\n      const schema = await project.getSchema();\n      console.log('Loaded schema:', schema);\n    }\n  } catch (error) {\n    console.error('Failed to load config:', error);\n  }\n}\n\nmain();","lang":"typescript","description":"Demonstrates loading a GraphQL config, accessing schema and documents, and retrieving a project schema asynchronously."},"warnings":[{"fix":"Update Node.js to >=16 and use import syntax. For CommonJS require, ensure you are using a compatible loader or transpiler.","message":"Version 5 drops CommonJS support for Node.js < 16 and ESM is the primary module system.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Replace imports from 'graphql-config/helpers' with imports from 'graphql-config'.","message":"The 'graphql-config/helpers' subpath is deprecated; use 'graphql-config' exports directly.","severity":"deprecated","affected_versions":">=5.0.0"},{"fix":"Always validate config shape using TypeScript type GraphQLConfig or runtime checks.","message":"Schema and documents fields can be strings, arrays, or objects. Incorrect type may cause silent failures.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Set legacy: true if using the deprecated `.graphqlconfig` format. Prefer `.graphqlrc` or `graphql.config.*`.","message":"The 'legacy' option defaults to false in v5; old `.graphqlconfig` files may not be loaded unless legacy is set to true.","severity":"gotcha","affected_versions":">=5.0.0"},{"fix":"Install 'cosmiconfig-toml-loader' for TOML or ensure your config uses JSON or YAML without custom loaders.","message":"Removed support for JSON5 and YAML in cosmiconfig by default; explicit loaders required.","severity":"breaking","affected_versions":">=5.0.0"}],"env_vars":null,"search_vec":"'16':88 '5.1.6':20 'ad':67 'ad-hoc':66 'api':75 'apollo':93 'author':78 'code':57 'config':2,4,69,91 'configur':8 'consist':74 'cosmiconfig':51 'current':16 'defin':30 'document':32 'editor':13 'end':81 'end-us':80 'eslint':60 'extens':64 'file':41 'generat':58 'graphql':1,3,11,35,56,59,63,90 'graphql-rel':34 'handl':70 'hoc':68 'ide':15 'integr':54 'javascript':89 'js':44 'json':43 'layer':9 'librari':77 'loader':50 'multipl':49 'node':87 'offer':72 'provid':25 'regular':22 'relat':36 'relay':92 'releas':23 'requir':86 'schema':31 'set':37 'ship':83 'singl':40 'stabl':17 'standard':7 'support':48 'toml':52 'tool':12 'type':85 'typescript':46,84,94 'unifi':27 'unlik':65 'user':82 'version':18 'way':28 'yaml':42","created_at":"2026-06-07T16:53:36.777937+00:00","updated_at":"2026-06-07T16:53:36.777937+00:00","problems":[{"fix":"Use named import from 'graphql-config': import { loadConfigSync } from 'graphql-config'","cause":"Importing a subpath that does not exist in v5.","error":"Error: Cannot find module 'graphql-config/loadConfigSync'"},{"fix":"Use named import: import { loadConfig } from 'graphql-config'; or const { loadConfig } = require('graphql-config');","cause":"Incorrect default import or require usage.","error":"TypeError: graphql_config_1.loadConfig is not a function"},{"fix":"Ensure a .graphqlrc file (YAML/JSON/JS/TS) exists in the root directory or specify configPath.","cause":"Config file missing or not named correctly.","error":"ConfigError: Config file not found. Tried ..."},{"fix":"Verify schema field in config: it should be a valid URL, file path, or introspection JSON.","cause":"Provided schema URL or file is invalid or points to a non-existent endpoint.","error":"Error: GraphQL Schema validation error: ..."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://graphql-config.com","github":"https://github.com/kamilkisiela/graphql-config","docs":null,"changelog":null,"pypi":null,"npm":"graphql-config","openapi_spec":null,"status_page":null,"smithery":null,"categories":["development","testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}