graphql-tools

graphql-tools is the founding package of the GraphQL Tools ecosystem, historically used to build executable GraphQL schemas from SDL type definitions and resolver maps, mock APIs, and stitch multiple schemas together. As the ecosystem grew, that functionality was split into focused scoped packages (@graphql-tools/schema, @graphql-tools/utils, @graphql-tools/stitch, and dozens more) that are versioned, tested, and released independently.

Today the top-level graphql-tools npm package is a deprecated compatibility shim: its entire source is a single re-export of makeExecutableSchema from @graphql-tools/schema, plus a console warning telling consumers to migrate to the scoped packages. It still ships because a large share of the GraphQL ecosystem — tutorials, older codebases, and libraries like GraphQL Yoga’s docs — reference it directly, and 800k+ weekly downloads mean it can’t simply be removed.

Functionally, importing makeExecutableSchema from graphql-tools gets you the same behavior as importing it from @graphql-tools/schema: pass in typeDefs (SDL strings, DocumentNodes, or arrays of either) and a resolvers map, and get back a fully executable GraphQLSchema compatible with GraphQL.js, ready to hand to a server like GraphQL Yoga, Apollo Server, or express-graphql.

What You Get

• makeExecutableSchema - build a fully executable GraphQLSchema from SDL type definitions plus a resolvers map, without touching @graphql-tools/schema directly
• SDL-first schema authoring - describe your API as a GraphQL type-language string (or DocumentNode) rather than constructing GraphQLObjectType instances by hand
• Drop-in compatibility for older code - projects and tutorials written against pre-v5 graphql-tools APIs keep working without an import rewrite
• A direct path to the modular ecosystem - the runtime deprecation warning tells you exactly which scoped package (@graphql-tools/schema, @graphql-tools/utils, etc.) to migrate to
• GraphQL.js-compatible output - the schema produced works with any server or tool built against the standard GraphQLSchema type (GraphQL Yoga, Apollo Server, express-graphql)

Common Use Cases

• Maintaining a pre-modularization codebase - a team on an older graphql-tools import path keeps shipping without an immediate migration to @graphql-tools/schema
• Following legacy tutorials and Stack Overflow answers - many older GraphQL.js guides still reference import { makeExecutableSchema } from 'graphql-tools' verbatim
• Pairing with GraphQL Yoga - write typeDefs and resolvers with graphql-tools, then hand the resulting schema to createYoga to serve it over HTTP
• A stepping stone before migrating - install graphql-tools short-term while planning a move to the scoped @graphql-tools/* packages it now wraps

Under The Hood

Architecture The graphql-tools package (packages/graphql-tools in the ardatan/graphql-tools monorepo) has no architecture of its own left to trace: its entire src/index.ts is a two-line re-export of makeExecutableSchema from the sibling @graphql-tools/schema workspace package, followed by a console.warn deprecation notice. The real implementation lives in @graphql-tools/schema (packages/schema/src/makeExecutableSchema.ts), which composes buildASTSchema/buildSchema from graphql-js with @graphql-tools/merge (for combining multiple typeDefs/resolvers sources) and @graphql-tools/utils, then attaches resolvers via addResolversToSchema and validates them via assertResolversPresent. What breaks if this changes is nothing in graphql-tools itself — all risk lives one layer down in @graphql-tools/schema, which graphql-tools simply forwards to at its current pinned version range.

Tech Stack The monorepo is TypeScript (ES2022 target, bundler module resolution, strict mode) built with the bob build tool into dual CJS/ESM outputs with generated .d.ts/.d.cts typings, managed as an npm workspace (packages/, packages/loaders/, packages/executors/*, website). graphql-tools declares graphql ^14-^17 as a peer dependency and depends on @graphql-tools/schema plus tslib; it optionally depends on @apollo/client. The wider monorepo integrates changesets for versioned releases, Renovate for dependency updates, and a Next.js-based website workspace for documentation.

Code Quality The graphql-tools package itself ships no tests — there’s nothing to test beyond a re-export. Test coverage lives in the packages it forwards to: @graphql-tools/schema has a dedicated tests/ directory (schemaGenerator.test.ts, merge-schemas.spec.ts, snapshot fixtures) run via Jest across the monorepo, and the repo enforces ESLint and Prettier with a CI workflow gating pull requests. TypeScript strict mode plus noUnusedLocals/noUnusedParameters/noFallthroughCasesInSwitch keep the sibling implementation packages held to a tight bar even though graphql-tools’ own surface area is a single re-export.

What Makes It Unique The interesting thing about graphql-tools today isn’t a technical innovation — it’s an ecosystem-migration pattern: rather than silently changing behavior or hard-breaking imports when the project modularized, the maintainers kept the original package name alive as a thin, honestly-labeled compatibility shim with a runtime deprecation warning pointing at the real replacement. That choice, plus continuing heavy download volume, reflects how much of the GraphQL.js ecosystem still bootstraps schemas through this exact import path even years after the underlying logic moved to scoped packages.