GraphQL Config - One configuration for all your tools
TL;DR
- Visit our website graphql-config.com
- GraphQL Config is one simple place to store all your GraphQL Configurations for any GraphQL based tool
- Prisma recently transferred the project to The Guild — and we completely rewrote it and addressed more than ⅔ of the issues (and the remaining are waiting for feedback)
- We’ve already merged configurations from GCG, GraphQL Inspector, GraphQL CLI — and are looking to learn and integrate with GraphiQL, AppSync, Apollo, Gatsby, VS-Code extensions, Relay and the GraphQL team at Facebook and any GraphQL tool creators
- This is an alpha phase — we want your feedback, as a user and as a creator — Please create an issue or join our Discord channel
How Did We Get Here?
About 2 years ago Prisma came up with a great idea for the GraphQL community — Why repeat yourself in creating your configuration for each tool you use in your application.
So together with many developers from the GraphQL community, they introduced the GraphQL Config library and spec and many tools have since embraced that standard.
But time has passed and the library slowly became unmaintained.
Prisma were very kind and generous with moving the project forward and passing it to us.
So when we took over the GraphQL Config, our main goal was to bring it back to life and push it forward for the community.
We asked for feedback, looked at existing and new tools that came out since it was released, went through all the open issues and PRs, listened to your suggestions and got to work!
Our Main Goals Are
- Highly customizable and extensible
- More useful structure
- Flexible and helpful enough to become a standard in the community
- Make it platform-agnostic (Node, Browser)
Try It Out Today
We’ve already refactored most of the code, created a new structure, referenced all the related issues and released a new alpha version:
npm install graphql-config@nextyarn add graphql-config@nextNow we want to hear from you — GraphQL developers and GraphQL tool creators.
Here is a deeper dive into what we’ve done:
Different Formats of GraphQL Config File
The new GraphQL Config now allows to use JSON, YAML and JavaScript.
GraphQL Config Looks for:
.graphqlrc.graphqlrc.yaml.graphqlrc.yml.graphqlrc.json.graphqlrc.jsgraphql.config.js
The new config can also be created programmatically too.
It also accepts a config defined under graphql property in your package.json file.
We’re open to expand the range of file names and looking forward to hear more of your use cases.
New Structure
GraphQL Config allowed to indicate a single graphql file, an introspection file or a URL to an endpoint. That’s the past!
schema: './schema.graphql'
documents: './my/app/**/*.graphql'
extensions:
customConfig:
value: trueSchema
We’ve decided to expand GraphQL Config for variety
of sources of GraphQL Schema and rename schemaPath to just schema.
It accepts now not only a single file but also a glob pattern to match your modularized schema.
Allows to Generate Schema from:
- files matching a glob pattern (or a list of patterns)
- an explicit list of files
- an endpoint
- an introspection file
- TypeScript and JavaScript files
- and even more…
It was possible thanks to the concept of Loaders which we’ll talk about later in the article.
Documents
Majority of the GraphQL tools depend not only on Schema but Operations and Fragments, so we’ve decided to cover that use case too.
With the new GraphQL Config, you’re able to indicate files containing GraphQL operations and fragments (documents) and load them all within a single method.
GraphQL Config accepts not only .graphql files but also extracts documents from TypeScript and
JavaScript files, including JSX and TSX.
import React from 'react'
import gql from 'graphql-tag'
import { useQuery } from '@apollo/react-hooks'
// GraphQL Config is able to extract it!
const GET_USERS = gql`
{
user {
id
name
}
}
`
export function Users() {
const { loading, error, data } = useQuery(GET_USERS)
// ...
return <UsersList users={data.users} />
}Thanks to that, you can still write your operations and fragments with graphql-tag and put them in
your React components. GraphQL Config is smart enough to find and collect them.
Include and Exclude
Include and Exclude options are still relevant, but we improved and fixed the logic behind them.
Their purpose is to tell config’s consumer which files belongs to what project.
Files covered by schema or documents options are automatically included, there’s no need to include them twice.
Extensions
We also kept extensions and turned them into a first class citizen in GraphQL Config, making
them way more powerful than before.
schema: './schema/*.graphql'
extensions:
codegen:
generates:
./src/types.ts:
plugins:
- typescript
- typescript-resolversPluggable Loaders
The source of GraphQL Schema may differ, depending on the setup. In some projects SDL is kept within graphql files, others store it in code.
The new GraphQL Config is capable of loading schema from:
.graphqlfiles- introspection result file
- running endpoints
- Files on GitHub
- Files on Git repository
- files with documents wrapped with
graphql-tagand gatsby’sgraphql - documents with the magic comment
/* GraphQL */ - single JavaScript and TypeScript file that exports GraphQLSchema object, DocumentNode or schema as string
The possibilities are endless here!
The main idea behind loaders is to extend the default behavior of GraphQL Config and allow to load GraphQL Schema from many different sources.
Loaders are flexible enough to let you decide what exactly you want to use, even just to keep the bundle size smaller.
It also simplifies the codebase of GraphQL tools as they don’t need to take care of that work themselves anymore.
export const RelayLoader = {
loaderId() {
return 'relay-loader'
},
canLoad(pointer) {
return isReactFile(pointer)
},
load(pointer) {
const document = extractDocument(pointer)
return new Source({
location: pointer,
document
})
}
}We maintain a few loaders, but we believe the community will start to cover other use cases as well.
All Platforms
Our goal is to make GraphQL Config platform-agnostic.
The old version relied heavily on Node’s file system, which is a blocker in many cases.
Loader fits here perfectly.
Because it’s just an asynchronous function that receives an input and gives back a GraphQL Schema, it should work fine in browser and in any other environment.
Extensions
In the previous generation of GraphQL Config extensions namespace, there was a way to pass custom
information to the consumers of the config file, like libraries and IDE extensions.
We believe extensions should actually extend GraphQL Config’s behavior.
Take for example loaders. Imagine you want to collect operations and fragments from your Relay project. With the new GraphQL Config, you can write a loader and register it through a Relay Extension.
const RelayExtension = api => {
api.loaders.documents.register(RelayLoader)
return {
name: 'relay'
}
}The new extensions allows you to turn GraphQL Config into something fully customizable and to be
used in tools like Webpack!
Hooks
We believe that there’s a need to intercept the schema building process or to simply validate the config.
It’s not currently available but with your help and suggestions we could make it happen.
Environment Variables
In the new GraphQL Config, we’ve decided to support environment variables. It was a long time hanging and highly requested issue. Now the usage in JS config file is straightforward. It’s also very easy to use environment variables in YAML and JSON files.
schema: './schema.graphql'
include: ${INCLUDE_GLOB}Every ${ENV_VAR} in the config file is replaced with the actual value. We also allow for defaults.
Using ${ENV_VAR:foo} results in foo.
Easier to Contribute
We also wanted to make the codebase itself easy to understand and contribute to.
Our first task was to bring the repository back to life by updating the build and test setup.
The graphql-config package now ships with CommonJS and ES Modules thanks to Rollup and
TypeScript. Tests are done thanks to Jest. The codebase stays consistent because of
Prettier and ESLint on top.
We also migrated from Travis to GitHub Actions and run tests on Node 8, 10 and 12.
To keep dependencies always up to date and to make sure no new release breaks GraphQL Config’s logic, we decided to use Dependabot.
We also addressed more than 70% of the issues and open PRs (and the remaining are waiting for feedback).
Start using it today!
Even though we are in an alpha phase, If you’re the author or maintainer of a GraphQL library or another related tool, we encourage you to adopt the GraphQL Config standard.
Please link to this GitHub issue to track the progress.
If you have a project that use those tools, we encourage you to try it out in your current project.
We will support and answer all your questions on Github and on our Discord channel.
Join our newsletter
Want to hear from us when there's something new? Sign up and stay up to date!
By subscribing, you agree with Beehiiv’s Terms of Service and Privacy Policy.
Recent issues of our newsletterSimilar articles
Announcing Accounts.js 1.0 Release Candidate
Introducing Accounts.js 1.0 Release Candidate, an end to end authentication and accounts management solution.
Building Open Source GraphQL Security
Learn how open-source boosts GraphQL security and explore defensive and offensive tools, resources, and best practices to protect your GraphQL APIs.
Open Source composition and validation library for Apollo Federation
Introducing MIT licensed drop-in replacement for the Apollo Federation composition library.
GraphQLConf 2023 Recap
Explore the highlights of GraphQLConf 2023. Learn about the latest trends in GraphQL, from gateway solutions to composite schemas and innovative projects.