graphql-tools — Utilities for Building and Transforming GraphQL Schemas

Introduction

graphql-tools is a collection of utilities maintained by The Guild for working with GraphQL schemas in JavaScript and TypeScript. Originally created by Apollo, the package provides the foundational makeExecutableSchema function used by most Node.js GraphQL servers, along with tools for schema stitching, mocking, merging, and transformation. It serves as the standard toolkit for programmatic schema manipulation in the GraphQL ecosystem.

What graphql-tools Does

• Creates executable GraphQL schemas from SDL type definitions and resolver maps with makeExecutableSchema
• Stitches multiple GraphQL schemas together into a unified gateway schema
• Generates mock resolvers automatically for rapid prototyping and testing
• Transforms existing schemas by renaming types, filtering fields, or wrapping resolvers
• Loads GraphQL schemas and documents from files, URLs, code-first sources, and databases

Architecture Overview

graphql-tools is organized as a collection of scoped npm packages under @graphql-tools/*. The core @graphql-tools/schema package provides makeExecutableSchema, which takes SDL strings and resolver maps and produces a fully functional GraphQLSchema object. The @graphql-tools/stitch package implements schema stitching, merging remote schemas through type merging and delegation. The @graphql-tools/mock package generates automatic mock resolvers based on schema types. The @graphql-tools/wrap package enables schema transformations via a composable transform pipeline. Each package is independently installable, keeping bundle sizes small.

Self-Hosting & Configuration

• Install only the packages you need: @graphql-tools/schema for basic schema building, @graphql-tools/stitch for stitching
• Use makeExecutableSchema as a drop-in replacement for building schemas in any Node.js GraphQL server
• Configure schema loaders to pull schemas from .graphql files, HTTP endpoints, or Git repositories
• Apply schema transforms to rename, filter, or extend types when combining schemas
• No runtime configuration files needed — all setup is done programmatically in JavaScript

Key Features

• makeExecutableSchema — the industry-standard function for creating GraphQL schemas from SDL and resolvers
• Schema stitching with type merging for combining multiple GraphQL APIs into a single unified gateway
• Automatic mock generation that creates realistic fake data based on your schema types
• Schema transformation pipeline for wrapping, filtering, renaming, and extending existing schemas
• Modular package architecture — install only what you use, from schema building to remote schema loading

Comparison with Similar Tools

• Apollo Server — a full GraphQL server that historically bundled graphql-tools; graphql-tools provides the schema utilities used underneath
• GraphQL Mesh — a gateway tool built on top of graphql-tools that adds connectors for REST, gRPC, and other non-GraphQL sources
• Apollo Federation — a distributed architecture using subgraph composition; graphql-tools stitching offers an alternative merging approach without requiring the Federation specification
• Nexus — a code-first schema builder for TypeScript; graphql-tools focuses on SDL-first schemas with resolver maps
• Pothos — a TypeScript-first schema builder using a builder pattern; graphql-tools uses the classic typeDefs + resolvers approach

FAQ

Q: Is graphql-tools still maintained now that Apollo does not own it? A: Yes. The Guild (the open-source organization behind GraphQL Yoga, Envelop, and GraphQL Code Generator) actively maintains graphql-tools. It receives regular updates and security patches.

Q: What is the difference between schema stitching and Apollo Federation? A: Schema stitching (via graphql-tools) merges schemas at the gateway level using type merging and delegation. Apollo Federation uses a composition specification with subgraph directives. Stitching is more flexible; Federation provides a more structured, standardized approach.

Q: Can I use graphql-tools with any GraphQL server? A: Yes. makeExecutableSchema produces a standard GraphQLSchema object that works with any server — Apollo Server, GraphQL Yoga, Express GraphQL, Mercurius, or custom implementations.

Q: How does schema mocking work? A: The @graphql-tools/mock package reads your schema types and generates resolvers that return realistic fake data. You can customize mocks for specific types or fields while letting the rest auto-generate.

Sources

• https://github.com/ardatan/graphql-tools
• https://the-guild.dev/graphql/tools