Configuring Apollo projects

How to configure Apollo VS Code and CLI with apollo.config.js

Apollo projects are configured using an apollo.config.js file at the root of the project. This config file powers editor integrations and the Apollo CLI. The configuration file how Apollo projects are setup. There are two types of projects, client and service which can be in the same configuration file if necessary.

Configuring a client project

Configuration of a client project is done through a top level client key in the config. In the simplest form, this is meant to link a client to a service:

module.exports = {
  client: {
    service: 'my-apollo-service',
  },
};

Linking a service

Service’s can be linked in one of three ways:

  • using the schema registry
  • using a remote endpoint
  • using a local schema file

Schema registry

To use the schema registry, pass the id of the service from Engine as the value for service:
module.exports = {
  client: {
    service: 'my-apollo-service',
  },
};
If a schema tag is being used, it can be included in the config after the service id:
module.exports = {
  client: {
    service: 'my-apollo-service@beta',
  },
};

Remote endpoint

Remote endpoints can be used to pull down a schema from a running service. This can be configured like so:

module.exports = {
  client: {
    service: {
      name: 'github',
      url: 'https://api.github.com/graphql',
      // optional headers
      headers: {
        authorization: 'Bearer lkjfalkfjadkfjeopknavadf',
      },
      // optional disable SSL validation check
      skipSSLValidation: true,
    },
  },
};

Local schema

In some cases, teams may have a local generated file of their schema they want to link. This can be either a .graphql file with the schma in SDL, or a saved introspection result in .json. To link a client with a local file, configure the project like this:

module.exports = {
  client: {
    service: {
      name: 'my-service-name',
      localSchemaFile: './path/to/schema.graphql',
    },
  },
};

Loading operation and schema files

Client projects can contain both operations and schema definitions for local state with Apollo Client. By default, Apollo will look under a ./src directory to find all operations and SDL to extract. To configure which folders to include, and which to ignore, adjust the config like so:

module.exports = {
  client: {
    includes: ['./imports/**/*.js'],
    excludes: ['**/__tests__/**/*'],
  },
};

Custom tagged template name

When using GraphQL with JavaScript of TypeScript projects, it is common to use the gql tagged template literal to write out operations. If a different template literal is used, it can be configured like so:
module.exports = {
  client: {
    tagName: 'graphql',
  },
};

Typename addition

GraphQL clients like Apollo Client often add the __typename field to an operation automatically. This is turned on by default in Apollo projects but can be turned off by adding addTypename: false to the client config:
module.exports = {
  client: {
    addTypename: false,
  },
};

Custom schema directives

Client side applications with Apollo can use custom directives that aren’t meant to be sent to the server. By default, Apollo projects support the following client side only directives: @client for local state @rest for using apollo-link-rest @connection for custom pagignation with Apollo Client @type for dynamic type names with apollo-link-rest Futher configuration of client side directives can be done in two ways:
module.exports = {
  client: {
    clientOnlyDirectives: ['connection', 'type'],
    clientSchemaDirectives: ['client', 'rest'],
  },
};
clientOnlyDirectives are directives that should be stripped out of the operation before being sent to the server. An example of this is the @connection directive. clientSchemaDirectives are directives that indicate a portion of the operation that is not meant to be sent to the server. These directives are removed as well as the fields they are placed on. An example of this type of of directive is the @client directive.

Configuring a service project

Configuration of a service project is done through a top level service key in the config. In the simplest form, this is meant to link a service to the Apollo schema registry:
module.exports = {
  service: {
    name: 'my-apollo-service',
  },
};
Services can be configured to remove the need for using flags when using the Apollo CLI. By configuring a service in the config, commands like apollo service:push and apollo service:check can have all flags removed and just use the config

Loading a schema

Loading a schema for a service can be linked in one of two ways: using a remote endpoint using a local schema file

Remote endpoint

Remote endpoints can be used to pull down a schema from a running service. This can be configured like so:

module.exports = {
  service: {
    endpoint: {
      url: 'https://api.github.com/graphql',
      // optional headers
      headers: {
        authorization: 'Bearer lkjfalkfjadkfjeopknavadf',
      },
      // optional disable SSL validation check
      skipSSLValidation: true,
    },
  },
};

Local schema

In some cases, teams may have a local generated file of their schema they want to link. This can be either a .graphql file with the schma in SDL, or a saved introspection result in .json. To link a service with a local file, configure the project like this:

module.exports = {
  service: {
    localSchemaFile: './path/to/schema.graphql',
  },
};
Edit on GitHub
// search box