GraphQL Config is a TypeScript configuration library and file convention, published on npm as graphql-config, that gives GraphQL developers and library authors one shared place to declare their schema and documents so that their tools, editors, and IDEs all read the same settings.

What it is

GraphQL Config is a library and configuration format for GraphQL development environments, distributed as the graphql-config package on npm under the MIT licence and maintained within The Guild's ecosystem. Its topic list places it among apollo, relay, intellij, devtools, graphql-schema and graphqlrc, which is to say in the middle of the everyday GraphQL toolchain rather than beside it. The project states two audiences explicitly: as a developer you gain a central place to set up libraries, tools and IDE extensions, and as a library author you get a set of useful methods and an easy-to-work-with API for handling configuration, loading GraphQL schemas, and loading files that contain GraphQL operations and fragments.

The problem it solves is duplicated configuration. Each GraphQL tool, editor extension and IDE plugin otherwise has to be told independently where the schema lives and which files hold operations and fragments. GraphQL Config replaces that scattering with one configuration, the convention its graphqlrc topic refers to, expressed in a short YAML document such as "schema: ./schema.json" alongside "documents: ./src/components/**/*.jsx". The project describes itself as one configuration for all your GraphQL tools, supported by most tools, editors and IDEs.

Key capabilities

• A single configuration document declaring both schema and documents entries, as shown in the README's YAML example.
• Schema loading for tools and editors, so each consumer does not have to implement schema discovery for itself.
• Loading of files containing GraphQL operations and fragments, not only the schema definition.
• A programmatic API, described as a set of useful methods and an easy-to-work-with API, aimed at library authors.
• Configuration handling factored out of individual tools, so their maintainers no longer reimplement it.
• Adoption across the GraphQL toolchain, including Apollo and Relay clients and IntelliJ-based IDEs, according to the project's topics.
• Distribution as the graphql-config npm package, with documentation hosted at graphql-config.com.

Who uses it and how

• Application developers who want one central place to set up their libraries, tools and IDE extensions instead of configuring each one separately.
• Library authors who would otherwise maintain their own code for handling configuration, loading schemas and reading files of operations and fragments.
• Teams working in JavaScript and JSX codebases, as the documented example points at ./schema.json and ./src/components/**/*.jsx.
• Developers whose surrounding toolchain includes Apollo or Relay clients and IntelliJ-based editors, the integrations named in the project's topics.
• Members of The Guild community, whom the project directs to its Discord chat for issues and questions.

Getting started

Install the graphql-config package from npm, the distribution channel linked from the project's npm version badge. Installation and usage instructions are kept on the project's website at graphql-config.com rather than in the README itself.

How it compares

GraphQL Config is not itself a GraphQL client or server; it sits underneath the tools named in its own topic list, such as Apollo, Relay, IntelliJ-based IDEs and other GraphQL devtools, as the shared configuration layer they read. Rather than competing with those tools, it is the format they converge on, which is why the project describes itself as supported by most tools, editors and IDEs.

When to use it — and when not to

Because it is a library and a configuration convention rather than a hosted service, there is no database, storage layer or mail server for anyone to operate, and the cost of adoption is mainly agreeing on the configuration file. It is a poor fit if your project uses a single GraphQL tool with its own settings and you have no intention of sharing configuration across editors, libraries or IDEs. The honest caveat is that the README excerpt is sparse: installation and usage are deferred to the external website, the repository carries 30 open issues, and no release history is recorded here, so the website documentation is worth reading before committing.

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