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 Hive Gateway. 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 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
For example, with GraphQL Hive CLI you can publish this subgraph with the following command:
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;