The Guild LogoThe Guild Monogram

GraphQL Config

Get Started

Writing and Consuming Extensions#

The main purpose of GraphQL Config Extensions is to pass information to extension's consumer in order to extend the behavior of GraphQL Config's logic.

GraphQL Config ships TypeScript declaration files so let's make use of them in following examples.

How to write extensions#

In order to make sure you write extensions correctly, import and use theGraphQLExtensionDeclaration type from graphql-config package. Thanks to TypeScript, you get autocompletion and in-editor validation.

The main requirement of an extension is its name. Providing a name lets GraphQL Config to match the extension with its namespace in the config file.

import { GraphQLExtensionDeclaration } from 'graphql-config' const InspectorExtension: GraphQLExtensionDeclaration = api => { return { name: 'inspector' } }

Schema Middlewares#

GraphQL Config lets you intercept the GraphQL Schema loading process which may be helpful when dealing with custom directives like in Relay or Apollo Federation. We call it Middlewares.

import { GraphQLExtensionDeclaration } from 'graphql-config' const RelayExtension: GraphQLExtensionDeclaration = api => { api.loaders.schema.use(document => { // The middleware receives a DocumentNode object // Adds relay directives // Returns a new DocumentNode return addRelayToDocumentNode(document) }) return { name: 'relay' } }

Consuming extension#

As a GraphQL tool author you will likely want to load the config and register your extension in order to understand user's configuration.

import { loadConfig } from 'graphql-config' import { InspectorExtension } from './extension' async function main() { const config = await loadConfig({ extensions: [InspectorExtension] }) }

Synchronous version: loadConfigSync

Now that everything is ready, GraphQL Config understands there's the Inspector extension.

In order to access information stored in the config file, do the following:

async function main() { // ... code from previous steps // Reads configuration of a default project const project = config.getDefault() // Reads configuration of a named project const project = config.getProject('admin') // Reads extenion's configuration defined in a project const inspectorConfig = project.extension('inspector') // Given following config file: // // schema: './schema.graphql' // extensions: // inspector: // validate: true // // You're able to get `validate`: if (inspectorConfig.validate === true) { // ... } }

Getting GraphQLSchema is straightforward: each project has getSchema(): Promise<GraphQLSchema> method.

async function main() { // ... code from the previous example if (inspectorConfig.validate === true) { const schema = await project.getSchema() validateSchema(schema) } }

GraphQL Config is able to generate a schema not only as GraphQLSchema object, but also as a DocumentNode. (For more info, read the API reference of GraphQLProjectConfig.) It's also capable of loading operations and fragments.

Registering Loaders#

In previous examples, we pointed GraphQL Config to the schema.graphql file. GraphQL Config, by default, understands the Introspection result stored in JSON file, GraphQL files (.graphql, .gql, .graphqls and .gqls) and the document returned by any functioning GraphQL endpoint (specified by URL).

In some cases, you may want to extend that behavior and teach GraphQL Config how to look for GraphQL SDL (modularized schema for example) across many JavaScript or TypeScript files.

It's now possible thanks to loaders.

The GraphQL Tools library has a few already written loaders that GraphQL Config uses. We mentioned the default loaders, but the repo contains a few extra ones.

For simplicity, we're going to use only the one responsible for extracting GraphQL SDL from code files.

import { CodeFileLoader } from '@graphql-tools/code-file-loader' const InspectorExtension: GraphQLExtensionDeclaration = api => { // Lets schema api.loaders.schema.register(new CodeFileLoader()) // documents api.loaders.documents.register(new CodeFileLoader()) return { name: 'inspector' } }

Let's say you have GraphQL SDL modularized across multiple TypeScript files, written like this:

import { gql } from 'graphql-tag' export const typeDefs = gql` type User { id: ID! name: String! } extend type Query { user(id: ID!): User! } `

With CodeFileLoader you can extract those GraphQL pieces:

schema: './src/modules/*.ts' # uses a glob pattern to look for files extensions: inspector: validate: true

There are two kinds of loaders. One is responsible for handling schemas, and the other covers Operations and Fragments (we call them both Documents).

To read more about loaders, please check "Loaders" chapter