Getting Started

Mesh Compose is a tool for composing non-GraphQL and GraphQL sources into a supergraph, that can be served by Hive Gateway or other gateways such as Apollo Gateway, Apollo Router or Cosmo Router.

Mesh Compose can also be used for transforming non-federation GraphQL sources into a Apollo Federation compatible subgraph.

Full overview of Mesh Compose features:

• Convert non-GraphQL sources to a GraphQL subgraph
• Convert non-federation GraphQL sources to a federated subgraph
• Transform subgraphs (rename, prefix, suffix fields and types etc.)
• Extend the supergraph with additional type definitions
• Adding an authentication layer using auth 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

Node.js is a pre-requisite for GraphQL Mesh. You can install Compose CLI with your favorite package manager:

npm i @graphql-mesh/compose-cli

pnpm add @graphql-mesh/compose-cli

yarn add @graphql-mesh/compose-cli

bun add @graphql-mesh/compose-cli

Compose Configuration

You need to create a Mesh config file in the root of your project directory. The following list of files are loaded by default, sorted by priority:

• mesh.config.ts (recommended)
• mesh.config.mts
• mesh.config.cts
• mesh.config.js
• mesh.config.mjs
• mesh.config.cjs

This example loads a GraphQL subgraph from the Countries API. Then the compose configuration should be exported as composeConfig.

import { defineConfig, 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 {
  createPrefixTransform,
  defineConfig,
  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:

npx 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:

npx 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

Run the Supergraph / Subgraph

Easiest way to run the supergraph is to use Hive Gateway.

npm i @graphql-hive/gateway

Then serve the supergraph with:

npx hive-gateway supergraph

Learn more;