---
description:
  GraphQL Mesh Compose allows to compose non GraphQL and GraphQL sources into a supergraph
---

import { Callout, Cards } from '@theguild/components'

# Getting Started

Mesh Compose is a tool for composing non-GraphQL and GraphQL sources into a supergraph, that can be
served by [Hive Gateway](https://the-guild.dev/graphql/hive/docs/gateway) or other gateways such as
[Apollo Gateway, Apollo Router or Cosmo Router](/v1/consume-in-other-gateways).

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](/v1/transforms) (rename, prefix, suffix fields and types etc.)
- Extend the supergraph with [additional type definitions](/v1/schema-extensions).
- Adding an authentication layer using [auth directives](/v1/auth)
- Adding a security layer for rate limiting using [`@rateLimit` directives](/v1/rate-limit)
- Generate a subgraph that is fully compatible with Federation tools so you can use it with any
  schema registry such as
  [Hive](https://the-guild.dev/graphql/hive/docs/gateway/supergraph-proxy-source) or
  [GraphOS](https://the-guild.dev/graphql/hive/docs/gateway/supergraph-proxy-source)

## Installation

[Node.js](https://nodejs.org) is a pre-requisite for GraphQL Mesh. You can install Compose CLI with
your favorite package manager:

```sh npm2yarn
npm i @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](https://countries.trevorblades.com).
Then the compose configuration should be exported as `composeConfig`.

```ts filename="mesh.config.ts"
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 }`.

<Callout>
  [See the source handlers section to learn more about handlers](/v1/source-handlers).
</Callout>

#### 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`.

<Callout>[See the transforms section to learn more about transforms](/v1/transforms).</Callout>

For example, the following configuration adds `Countries_` to the types and fields of the subgraph
by using [Prefix Transform](/v1/transforms/prefix).

```ts filename="mesh.config.ts" {12-16}
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.

<Callout>
  [See Schema Extension section to learn how to use `@resolveTo` directive to stitch
  subgraphs](/v1/schema-extensions).
</Callout>

```ts filename="mesh.config.ts" {14-25}
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`](https://github.com/ardatan/whatwg-node) 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.

```ts filename="mesh.config.ts" {7}
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.

```ts filename="mesh.config.ts" {7}
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:

```sh
npx mesh-compose -o supergraph.graphql
```

<Callout>
  [In order to serve the supergraph, you need to setup Hive
  Gateway](https://the-guild.dev/graphql/hive/docs/gateway).
</Callout>

## Generating the individual subgraphs for Schema Registry

If you want to publish the subgraphs to a schema registry such as
[Hive](https://the-guild.dev/graphql/hive/docs/gateway/supergraph-proxy-source) or
[GraphOS](https://the-guild.dev/graphql/hive/docs/gateway/supergraph-proxy-source), you can generate
the subgraphs by running the following command:

```sh
npx mesh-compose --subgraph SUBGRAPH_NAME -o subgraph.graphql
```

<Callout>
For example, with GraphQL Hive CLI you can publish this subgraph with the following command:

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

</Callout>

## Run the Supergraph / Subgraph

Easiest way to run the supergraph is to use
[Hive Gateway](https://the-guild.dev/graphql/hive/docs/gateway).

```sh
npm i @graphql-hive/gateway
```

Then serve the supergraph with:

```sh
npx hive-gateway supergraph
```

Learn more;

<Cards>
  <Cards.Card
    arrow
    title="Serve the generated API with Hive Gateway"
    href="https://the-guild.dev/graphql/hive/docs/gateway"
  />
  <Cards.Card
    arrow
    title="Serve the generated API with other gateways"
    href="/v1/consume-in-other-gateways"
  />
</Cards>
