How to Use Schema Stitching in GraphQL: Syntax and Example

Use makeExecutableSchema to create schemas and stitchSchemas to combine them into one unified schema. Schema stitching lets you merge multiple GraphQL APIs so clients can query them as a single API.

Syntax

Schema stitching involves creating individual schemas and then combining them using stitchSchemas. You define type definitions and resolvers for each schema, then merge them.

• makeExecutableSchema({ typeDefs, resolvers }): Creates a schema from type definitions and resolvers.
• stitchSchemas({ subschemas }): Combines multiple schemas into one.

javascript

const { makeExecutableSchema } = require('@graphql-tools/schema');
const { stitchSchemas } = require('@graphql-tools/stitch');

const schema1 = makeExecutableSchema({
  typeDefs: `type Query { hello: String }`,
  resolvers: { Query: { hello: () => 'Hello from schema1' } }
});

const schema2 = makeExecutableSchema({
  typeDefs: `type Query { world: String }`,
  resolvers: { Query: { world: () => 'World from schema2' } }
});

const stitchedSchema = stitchSchemas({
  subschemas: [
    { schema: schema1 },
    { schema: schema2 }
  ]
});

Example

This example shows how to stitch two simple schemas with separate queries into one schema. The combined schema allows querying both hello and world fields in a single request.

javascript

const { graphql } = require('graphql');
const { makeExecutableSchema } = require('@graphql-tools/schema');
const { stitchSchemas } = require('@graphql-tools/stitch');

const schema1 = makeExecutableSchema({
  typeDefs: `type Query { hello: String }`,
  resolvers: { Query: { hello: () => 'Hello from schema1' } }
});

const schema2 = makeExecutableSchema({
  typeDefs: `type Query { world: String }`,
  resolvers: { Query: { world: () => 'World from schema2' } }
});

const stitchedSchema = stitchSchemas({
  subschemas: [
    { schema: schema1 },
    { schema: schema2 }
  ]
});

const query = `{
  hello
  world
}`;

graphql(stitchedSchema, query).then(result => {
  console.log(JSON.stringify(result, null, 2));
});

Output

{
  "data": {
    "hello": "Hello from schema1",
    "world": "World from schema2"
  }
}

Common Pitfalls

Common mistakes when using schema stitching include:

• Not properly merging overlapping types or fields, causing conflicts.
• Forgetting to forward resolvers for stitched fields, leading to missing data.
• Using incompatible versions of stitching libraries.
• Not handling nested queries correctly across schemas.

Always test combined queries and check for resolver conflicts.

javascript

/* Wrong: Overlapping Query type without merging */
const schemaA = makeExecutableSchema({
  typeDefs: `type Query { hello: String }`,
  resolvers: { Query: { hello: () => 'Hi' } }
});

const schemaB = makeExecutableSchema({
  typeDefs: `type Query { hello: String }`,
  resolvers: { Query: { hello: () => 'Hello' } }
});

// Stitching these without merging causes conflict
const badStitched = stitchSchemas({ subschemas: [
  { schema: schemaA },
  { schema: schemaB }
] });

/* Right: Rename or merge fields to avoid conflict */
const schemaBFixed = makeExecutableSchema({
  typeDefs: `type Query { helloB: String }`,
  resolvers: { Query: { helloB: () => 'Hello' } }
});

const goodStitched = stitchSchemas({ subschemas: [
  { schema: schemaA },
  { schema: schemaBFixed }
] });

Quick Reference

Concept	Description
makeExecutableSchema	Creates a GraphQL schema from type definitions and resolvers.
stitchSchemas	Combines multiple schemas into one unified schema.
subschemas	Array of schemas to merge in stitchSchemas.
Resolvers	Functions that fetch data for schema fields.
TypeDefs	GraphQL schema language definitions for types and queries.

Key Takeaways

Use makeExecutableSchema to create individual schemas before stitching.

Combine schemas with stitchSchemas and provide subschemas array.

Avoid overlapping types or fields without merging or renaming.

Test stitched schema queries to ensure resolvers work correctly.

Keep stitching libraries updated to avoid compatibility issues.