Getting Started

GraphQL Mesh Compose is a tool that allows you to compose non-GraphQL and GraphQL sources into a supergraph, so that you can serve it using GraphQL Mesh Serve.

If you use other routers such as Apollo Gateway, Apollo Router or Cosmo Router, you can still use Mesh Compose to convert non-federated sources to a federated subgraph. Learn more about consuming in other routers.

Basically GraphQL Mesh Compose allows you to do;

• Convert non-GraphQL sources to a GraphQL subgraph
• Convert non-federated GraphQL sources to a federated subgraph
• Transform the subgraphs using transforms
• Extend the supergraph using additionalTypeDefs
• Adding an authentication layer using @auth or @skipAuth directives
• Adding a security layer for rate limiting using @rateLimit directives
• Generate a subgraph that is fully compatible with Federation tools so you can use it with any schema registry such as Hive or GraphOS

Installation

In order to get started, you need to have Node.js installed in your environment. Then, you can install Compose CLI with your favorite package manager:

npm i @graphql-mesh/compose-cli

Compose Configuration

You need to create a mesh.config.ts file in the root of your project directory. The following example loads a GraphQL subgraph from the Countries API. Then the compose configuration should be exported as composeConfig.

import {
  defineConfig as defineComposeConfig,
  loadGraphQLHTTPSubgraph
} from '@graphql-mesh/compose-cli'
 
export const composeConfig = defineConfig({
  subgraphs: [
    {
      sourceHandler: loadGraphQLHTTPSubgraph('Countries', {
        endpoint: 'https://countries.trevorblades.com'
      })
    }
  ]
})

Let’s take a deeper look at the configuration file.

Configuring Subgraphs using subgraphs

Subgraphs are the sources that you want to compose. subgraphs array contains a list of SubgraphConfig objects. Each object has the following structure;

Loading the source as a subgraph using sourceHandler

The source handler is responsible of loading the source as a GraphQL subgraph for the composition. You can use the built-in source handlers or create your own custom source handler. Source handlers returns an object of { schema$: Promise<GraphQLSchema>, name: string }.

Transforming the loaded subgraph using transforms

An array of transforms that you want to apply to the subgraph. You can use the built-in transforms or create your own. Transforms are functions that take a GraphQLSchema and return a GraphQLSchema.

For example, the following configuration adds Countries_ to the types and fields of the subgraph by using Prefix Transform.

import {
  defineConfig as defineComposeConfig,
  loadGraphQLHTTPSubgraph
} from '@graphql-mesh/compose-cli'
 
export const composeConfig = defineConfig({
  subgraphs: [
    {
      sourceHandler: loadGraphQLHTTPSubgraph('Countries', {
        endpoint: 'https://countries.trevorblades.com'
      }),
      transforms: [
        createPrefixTransform({
          value: 'Countries_'
        })
      ]
    }
  ]
})

Extending the supergraph using additionalTypeDefs

You can extend your supergraph, by adding additional type definitions to the schema. Using this option, you can declare additional resolvers to stitch the subgraphs.

export const composeConfig = defineConfig({
  subgraphs: [
    {
      sourceHandler: loadGraphQLHTTPSubgraph('authors', {
        endpoint: `http://localhost:3001/graphql`
      })
    },
    {
      sourceHandler: loadGraphQLHTTPSubgraph('books', {
        endpoint: `http://localhost:4002/graphql`
      })
    }
  ],
  additionalTypeDefs: /* GraphQL */ `
    extend type Book {
      author: Author
        @resolveTo(
          sourceName: "authors"
          sourceTypeName: "Query"
          sourceFieldName: "authors"
          keyField: "authorId"
          keysArg: "ids"
        )
    }
  `
})

Transforming the supergraph using transforms

If you want to transform the supergraph instead of subgraphs, you can use the transforms option on higher level, instead of subgraph level.

Replacing HTTP client using fetch (Advanced usage only)

By default, Mesh uses @whatwg-node/fetch as a environment agnostic Fetch API implementation. We highly recommend using this option to replace the fetch implementation if you know what you are doing.

import fetch from 'node-fetch'
 
export const composeConfig = defineConfig({
  subgraphs: [
    // ...
  ],
  fetch
})

Changing the base directory using cwd (Advanced usage only)

By default, Mesh uses the current working directory as the base directory for the configuration file. You can use this option to change the base directory.

export const composeConfig = defineConfig({
  subgraphs: [
    // ...
  ],
  cwd: __dirname
})

Generating the Supergraph

Just like Federation’s Supergraph document, Compose CLI outputs unifiedgraph.graphql file that contains all the annotations for the gateway.

You can generate the supergraph by running the following command:

mesh-compose > supergraph.graphql

Generating the individual subgraphs for Schema Registry

If you want to publish the subgraphs to a schema registry such as Hive or GraphOS, you can generate the subgraphs by running the following command:

mesh-compose --subgraph SUBGRAPH_NAME > subgraph.graphql

hive schema:publish \
  --registry.accessToken YOUR_TOKEN_HERE \
  --service="reviews" \
  --url="http://fake.com/reviews/graphql" \
  --author "Me" \
  --commit "Second" \
  wiki-subgraph.graphql