Required dependencies

npm install graphql
npm install @graphql-tools/utils @graphql-tools/schema @graphql-tools/merge
npm install @graphql-tools/load @graphql-tools/load-files
npm install @graphql-tools/executor
npm install @graphql-tools/documents
# Apollo executor adapter (optional)
npm install @graphql-tools/executor-apollo-link @apollo/client
# Envelop executor plugin (optional)
npm install @graphql-tools/executor-envelop @envelop/core @graphql-tools/wrap
# urql exchange (optional)
npm install @graphql-tools/executor-urql-exchange urql
# yoga executor (optional)
npm install @graphql-tools/executor-yoga graphql-yoga

No native modules, pod install, or Android linking steps required. All packages are pure JavaScript/TypeScript.

Project setup

1. Copy the source/ directory into your project, e.g. src/graphql-tools/.
2. Add path aliases in tsconfig.json if you want to import from the source directly instead of the published npm packages:

{
  "compilerOptions": {
    "paths": {
      "@graphql-tools/utils": ["./src/graphql-tools/utils/src/index.ts"],
      "@graphql-tools/schema": ["./src/graphql-tools/schema/src/index.ts"],
      "@graphql-tools/executor": ["./src/graphql-tools/executor/src/index.ts"],
      "@graphql-tools/documents": ["./src/graphql-tools/documents/src/index.ts"]
    }
  }
}

3. Ensure "moduleResolution": "bundler" or "node16" is set; the source uses .js extensions in imports which require modern resolution.
4. No required environment variables. Loaders that fetch remote schemas (loaders/url) expect a standard fetch global (Node 18+ or a polyfill via cross-fetch).
5. For Jest, register @graphql-tools/jest-transform in jest.config.ts:

transform: { '\\.graphql$': '@graphql-tools/jest-transform' }

Public API

printExecutableGraphQLDocument

import { printExecutableGraphQLDocument } from '@graphql-tools/documents';

function printExecutableGraphQLDocument(ast: DocumentNode): string;

Prints a DocumentNode as a canonical, deterministic GraphQL SDL string. Use this when you need a stable hash key for persisted queries or want to strip client-only directives before sending to a server.

sortExecutableDocument

import { sortExecutableDocument } from '@graphql-tools/documents';

function sortExecutableDocument(document: DocumentNode): DocumentNode;

Returns a new DocumentNode with all definitions and fields sorted alphabetically. Use it before hashing a document to ensure two semantically identical queries always produce the same hash regardless of field ordering.

ExecutorLink

import { ExecutorLink } from '@graphql-tools/executor-apollo-link';
// (source: executors/apollo-link/src/index.ts)

class ExecutorLink extends ApolloLink {
  constructor(executor: Executor): ExecutorLink;
}

Wraps any Executor (including remote HTTP executors or mock executors) as an Apollo Client link. Drop it into an Apollo link chain wherever you would normally use HttpLink. Supports subscriptions via async iterables automatically.

useExecutor

import { useExecutor } from '@graphql-tools/executor-envelop';
// (source: executors/envelop/src/index.ts)

function useExecutor<TPluginContext extends Record<string, any>>(
  executor: Executor,
  opts?: ExecutorPluginOpts,
): Plugin<TPluginContext> & ExecutorPluginExtras;

Creates an Envelop plugin that proxies all GraphQL execution to a remote Executor, automatically fetching and caching the remote schema via introspection. Pass opts.polling (milliseconds) to periodically refresh the schema.

Working examples

Scenario - Canonical persisted query key generation

Produce a stable string key for a GraphQL document to use as a persisted query identifier, regardless of how the client wrote the query.

import { parse } from 'graphql';
import { sortExecutableDocument } from '@graphql-tools/documents';
import { printExecutableGraphQLDocument } from '@graphql-tools/documents';
import { createHash } from 'crypto';

const rawDocument = parse(`
  query GetUser {
    user {
      email
      id
      name
    }
  }
`);

const sorted = sortExecutableDocument(rawDocument);
const printed = printExecutableGraphQLDocument(sorted);
const hash = createHash('sha256').update(printed).digest('hex');

console.log('Persisted query key:', hash);
console.log('Canonical document:\n', printed);

Scenario - Apollo Client with a custom Executor

Replace HttpLink with ExecutorLink so Apollo Client delegates to any Executor — useful for testing, schema stitching, or adding middleware.

import { ApolloClient, InMemoryCache, gql } from '@apollo/client';
import { ExecutorLink } from '@graphql-tools/executor-apollo-link';
import { buildHTTPExecutor } from '@graphql-tools/executor-http'; // from loaders/url

const executor = buildHTTPExecutor({
  endpoint: 'https://api.example.com/graphql',
  headers: { Authorization: `Bearer ${process.env.API_TOKEN}` },
});

const client = new ApolloClient({
  link: new ExecutorLink(executor),
  cache: new InMemoryCache(),
});

const result = await client.query({
  query: gql`
    query GetPosts {
      posts {
        id
        title
      }
    }
  `,
});

console.log(result.data);

Scenario - Envelop gateway with remote executor and schema polling

Build an Envelop-powered GraphQL gateway that sources its schema from a remote executor and refreshes it every 60 seconds.

import { envelop, useSchema } from '@envelop/core';
import { useExecutor } from '@graphql-tools/executor-envelop';
import { buildHTTPExecutor } from '@graphql-tools/executor-http';

const remoteExecutor = buildHTTPExecutor({
  endpoint: 'https://remote-api.example.com/graphql',
});

const getEnveloped = envelop({
  plugins: [
    useExecutor(remoteExecutor, {
      polling: 60_000,
      logWarn: (msg) => console.warn('[gateway]', msg),
    }),
  ],
});

// In your HTTP handler (e.g. Node http, Express, Fastify):
async function handleRequest(req: any, res: any) {
  const { execute, schema, contextFactory, parse, validate } = getEnveloped({ req });
  const body = await req.json();
  const document = parse(body.query);
  const errors = validate(schema, document);
  if (errors.length) {
    res.json({ errors });
    return;
  }
  const result = await execute({
    schema,
    document,
    contextValue: await contextFactory(),
    variableValues: body.variables,
  });
  res.json(result);
}

File walkthrough

• documents/src/index.ts - Re-exports printExecutableGraphQLDocument and sortExecutableDocument; the two public utilities for deterministic document handling.
• executor/src/index.ts - Barrel that re-exports everything from execution/, including execute, normalizedExecutor, and getVariableValues.
• executor/src/execution/execute.ts - Core executor implementation; a drop-in replacement for graphql-js execute with incremental delivery support.
• executor/src/execution/normalizedExecutor.ts - Wraps execute to always return a single result or async iterable, normalizing the return type.
• executor/src/execution/values.ts - Coerces and validates variable and argument values against a schema.
• executors/apollo-link/src/index.ts - Exports ExecutorLink; bridges Executor to Apollo Client's link chain.
• executors/envelop/src/index.ts - Exports useExecutor; Envelop plugin for remote schema proxying.
• executors/legacy-ws/src/index.ts - Executor for subscriptions-transport-ws (legacy WebSocket protocol).
• executors/urql-exchange/src/index.ts - urql exchange that delegates operations to an Executor.
• executors/yoga/src/index.ts - GraphQL Yoga-compatible executor adapter.

Common pitfalls and fixes

• .js extension resolution fails in Node CJS mode - Set "moduleResolution": "node16" or "bundler" in tsconfig.json; the source uses explicit .js extensions in all imports.
• @apollo/client default export varies between CJS and ESM - The apollo-link adapter handles this with (apolloImport as any)?.default ?? apolloImport; do not double-wrap the import yourself.
• fetch not defined in Node < 18 - Install cross-fetch and call import 'cross-fetch/polyfill' before any loader or URL executor is used.
• Envelop useExecutor schema not ready on first request - The schema is fetched asynchronously on first use; call ensureSchema() from the returned ExecutorPluginExtras during server startup to pre-warm it.
• Peer dependency version mismatch on graphql - All packages in this monorepo require graphql@^16; mixing graphql@15 causes silent type incompatibilities in schema stitching.
• ESM/CJS interop with @envelop/core - Envelop publishes both formats; if you see duplicate symbol errors, pin all envelop packages to the same minor version and ensure a single graphql instance via npm dedupe.

Vibe-coding prompt template

I have the graphql-tools monorepo source copied into `src/graphql-tools/` in my project.
I also have `USAGE.md` open which documents the real exports and working examples.

The upstream package is `graphql-tools` (graphql-tools monorepo).

Please help me integrate it into my project step by step:

1. Read `USAGE.md` to understand the available packages and their exports.
2. Check my existing `tsconfig.json` and update path aliases so imports from
   `@graphql-tools/executor`, `@graphql-tools/documents`, and
   `@graphql-tools/executor-apollo-link` resolve to `src/graphql-tools/`.
3. Wire up `ExecutorLink` from `src/graphql-tools/executors/apollo-link/src/index.ts`
   into my Apollo Client configuration, replacing the existing `HttpLink`.
4. Add `sortExecutableDocument` and `printExecutableGraphQLDocument` from
   `src/graphql-tools/documents/src/index.ts` to my persisted-query pipeline.
5. If I use Envelop, add the `useExecutor` plugin from
   `src/graphql-tools/executors/envelop/src/index.ts` with a 60-second polling interval.
6. Show me the final diff for each changed file and flag any peer dependency
   version issues to resolve before running the build.

License and credit

The upstream project is MIT licensed. See source/LICENSE if present, or refer to the graphql-tools GitHub repository and the npm packages under the @graphql-tools scope. Original authors: Uri Goldshtein, The Guild, and contributors.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

GraphQL Compose Programmatic Schema Builder

Automation, Utilities & Developer Tools

Free