How to Merge Multiple Schemas in GraphQL Easily

To merge multiple schemas in GraphQL, use @graphql-tools/merge for schema stitching or Apollo Federation for distributed schemas. These methods combine type definitions and resolvers into a single schema that your server can use.

Syntax

To merge multiple GraphQL schemas, you typically use mergeTypeDefs and mergeResolvers from @graphql-tools/merge. Then, you create an executable schema with makeExecutableSchema.

Key parts:

• typeDefs: GraphQL type definitions from each schema.
• resolvers: Resolver functions for each schema.
• mergeTypeDefs: Combines multiple typeDefs into one.
• mergeResolvers: Combines multiple resolvers into one.
• makeExecutableSchema: Builds the final schema from merged typeDefs and resolvers.

javascript

import { mergeTypeDefs, mergeResolvers } from '@graphql-tools/merge';
import { makeExecutableSchema } from '@graphql-tools/schema';

const mergedTypeDefs = mergeTypeDefs([typeDefs1, typeDefs2]);
const mergedResolvers = mergeResolvers([resolvers1, resolvers2]);

const schema = makeExecutableSchema({
  typeDefs: mergedTypeDefs,
  resolvers: mergedResolvers,
});

Example

This example shows how to merge two simple schemas: one for users and one for posts. It combines their type definitions and resolvers into a single schema.

javascript

import { ApolloServer } from 'apollo-server';
import { mergeTypeDefs, mergeResolvers } from '@graphql-tools/merge';
import { makeExecutableSchema } from '@graphql-tools/schema';

// Schema 1: User
const userTypeDefs = `
  type User {
    id: ID!
    name: String!
  }
  type Query {
    users: [User]
  }
`;

const userResolvers = {
  Query: {
    users: () => [
      { id: '1', name: 'Alice' },
      { id: '2', name: 'Bob' }
    ],
  },
};

// Schema 2: Post
const postTypeDefs = `
  type Post {
    id: ID!
    title: String!
    authorId: ID!
  }
  type Query {
    posts: [Post]
  }
`;

const postResolvers = {
  Query: {
    posts: () => [
      { id: 'a', title: 'Hello World', authorId: '1' },
      { id: 'b', title: 'GraphQL Rocks', authorId: '2' }
    ],
  },
};

// Merge typeDefs and resolvers
const mergedTypeDefs = mergeTypeDefs([userTypeDefs, postTypeDefs]);
const mergedResolvers = mergeResolvers([userResolvers, postResolvers]);

// Create executable schema
const schema = makeExecutableSchema({
  typeDefs: mergedTypeDefs,
  resolvers: mergedResolvers,
});

// Start Apollo Server
const server = new ApolloServer({ schema });

server.listen().then(({ url }) => {
  console.log(`Server ready at ${url}`);
});

Output

Server ready at http://localhost:4000/

Common Pitfalls

Common mistakes when merging schemas include:

• Not merging both typeDefs and resolvers, which causes missing fields or errors.
• Conflicting type names or fields without proper namespacing or merging strategies.
• Forgetting to create an executable schema after merging.
• Using incompatible versions of GraphQL tools.

Always ensure your schemas have unique type names or use schema stitching techniques to resolve conflicts.

javascript

/* Wrong: Merging only typeDefs without resolvers */
const mergedTypeDefs = mergeTypeDefs([typeDefs1, typeDefs2]);
// Missing mergeResolvers step
const schema = makeExecutableSchema({ typeDefs: mergedTypeDefs });

/* Right: Merge both typeDefs and resolvers */
const mergedResolvers = mergeResolvers([resolvers1, resolvers2]);
const schema = makeExecutableSchema({
  typeDefs: mergedTypeDefs,
  resolvers: mergedResolvers,
});

Quick Reference

Tips for merging GraphQL schemas:

• Use @graphql-tools/merge to combine typeDefs and resolvers.
• Always create an executable schema with makeExecutableSchema.
• Check for naming conflicts and resolve them before merging.
• Consider Apollo Federation for microservices with separate schemas.

Key Takeaways

Use @graphql-tools/merge to combine multiple typeDefs and resolvers into one schema.

Always create an executable schema after merging to use it in your GraphQL server.

Check for naming conflicts between schemas to avoid errors.

Apollo Federation is an alternative for merging schemas in distributed systems.

Merging only typeDefs without resolvers causes incomplete schemas and runtime errors.