graphql-config

What is graphql-config?

The graphql-config npm package provides a set of utilities to make it easier to configure and use GraphQL in your development environment. It allows for the centralization of GraphQL project configurations, making it simpler to share settings across different tools such as IDEs, GraphQL clients, and other utilities that work with GraphQL.

What are graphql-config's main functionalities?

Loading GraphQL Project Configuration

This feature allows you to load the GraphQL project configuration. The `loadConfig` function asynchronously loads the configuration from the default or specified configuration file.

const { loadConfig } = require('graphql-config');

async function main() {
  const config = await loadConfig();
  console.log(config);
}

main();

Getting Schema Information

This feature enables you to retrieve the GraphQL schema information from the configuration. It's useful for tools and applications that need to introspect the schema.

const { loadConfig } = require('graphql-config');

async function main() {
  const config = await loadConfig();
  const schema = await config.getDefault().getSchema();
  console.log(schema);
}

main();

Working with Endpoints

This feature allows for the management of GraphQL API endpoints within the configuration. It simplifies the process of switching between different environments or API versions.

const { loadConfig } = require('graphql-config');

async function main() {
  const config = await loadConfig();
  const endpoint = config.getDefault().endpoint('default');
  console.log(endpoint);
}

main();

Other packages similar to graphql-config

graphql-tools

graphql-tools is a package that provides a set of utilities for building and working with GraphQL schemas. It is similar to graphql-config in that it helps with GraphQL development, but it focuses more on schema creation, mocking, and stitching, rather than configuration management.

apollo-server

apollo-server is a community-driven, open-source GraphQL server. It's similar to graphql-config in the sense that it's used in GraphQL development environments. However, apollo-server focuses on building and running GraphQL servers, including features like schema definition, data fetching, and request handling, rather than on project configuration.

README

graphql-config

The README reflects new graphql-config protocol. Old graphql-config-parser documentation can be found here

The easiest way to configure your development environment with your GraphQL schema (supported by most tools, editors & IDEs)

Supported by...

Language Services

• graphql-language-service - An interface for building GraphQL language services for IDEs (pending)

Editors

• js-graphql-intellij-plugin - GraphQL language support for IntelliJ IDEA and WebStorm, including Relay.QL tagged templates in JavaScript and TypeScript (pending)
• atom-language-graphql - GraphQL support for Atom text editor (pending)

Tools

• babel-plugin-react-relay - Babel compile step to process your Relay.QL queries (pending)
• babel-plugin-transform-relay-hot - Wrapper under BabelRelayPlugin with hot reload (pending)
• eslint-plugin-graphql - An ESLint plugin that checks tagged template strings against a GraphQL schema (pending)
• webpack-plugin-graphql-schema-hot - Webpack plugin which tracks changes in your schema and generates its introspection in json and txt formats (pending)

Did we forget a tool/editor? Please add it here.

Go to graphql-config library docs

Usage

tl;dr

Install graphql-cli and run graphql init. Answer a few simple questions and you are set up!

You can either configure your GraphQL endpoint via a configuration file .graphqlconfig (or .graphqlconfig.yaml) which should be put into the root of your project

Simplest use case

The simplest config specifies only schemaPath which is path to the file with introspection results or corresponding SDL document

{
  "schemaPath": "schema.graphql"
}

or

{
  "schemaPath": "schema.json"
}

Specifying includes/excludes files

You can specify which files are included/excluded using the corresponding options:

{
  "schemaPath": "schema.graphql",
  "includes": ["*.graphql"],
  "excludes": ["temp/**"]
}

Note: excludes and includes fields are globs that should match filename. So, just temp or temp/ won't match all files inside the directory. That's why the example uses temp/**

Specifying endpoint info

You may specify your endpoints info in .graphqlconfig which may be used by some tools. The simplest case:

{
  "schemaPath": "schema.graphql",
  "extensions": {
    "endpoints": {
      "dev": "https://example.com/graphql"
    }
  }
}

In case you need provide additional information, for example headers to authenticate your GraphQL endpoint or an endpoint for subscription, you can use expanded version:

{
  "schemaPath": "schema.graphql",
  "extensions": {
    "endpoints": {
      "dev": {
        "url": "https://example.com/graphql",
        "headers": {
          "Authorization": "Bearer ${env:AUTH_TOKEN_ENV}"
        },
        "subscription": {
          "url": "ws://example.com/graphql",
          "connectionParams": {
            "Token": "${env:YOUR_APP_TOKEN}"
          }
        }
      }
    }
  }
}

Note: do not save secure information in .graphqlconfig file. Use Environment variables for that like in the example above.

In case if you have multiple endpoints use the following syntax:

{
  "schemaPath": "schema.graphql",
  "extensions": {
    "endpoints": {
      "prod": {
        "url": "https://your-app.com/graphql",
        "subscription": {
          "url": "wss://subscriptions.graph.cool/v1/instagram"
        }
      },
      "dev": {
        "url": "http://localhost:3000/graphql",
        "subscription": {
          "url": "ws://localhost:3001"
        }
      }
    }
  }
}

Multi-project configuration (advanced)

TBD

Refer to specification use-cases for details

How it works

This project aims to be provide a unifying configuration file format to configure your GraphQL schema in your development environment.

Additional to the format specification, it provides the graphql-config library, which is used by all supported tools and editor plugins. The library reads your provided configuration and passes the actual GraphQL schema along to the tool which called it.

graphql-config API

Here are very basic examples of how to use graphql-config library.

You can find the detailed documentation here

getGraphQLProjectConfig

NOTE: if your tool works on per-file basis (e.g. editor plugin, linter, etc) use getGraphQLConfig function

getGraphQLProjectConfig should be used by tools that do not work on per-file basis

import { getGraphQLProjectConfig } from 'graphql-config'

const config = getGraphQLProjectConfig('./optionalProjectDir', 'optionalProjectName')
const schema = config.getSchema()
// use schema for your tool/plugin

getGraphQLConfig

getGraphQLConfig should be used by tools that work on per-file basis (editor plugins, linters, etc.)

import { getGraphQLConfig } from 'graphql-config'

const config = getGraphQLConfig('./optionalProjectDir')
const schema = config.getConfigForFile(filename).getSchema()
// use schema for your tool/plugin

Help & Community

Join our Slack community if you run into issues or have questions. We love talking to you!