GraphQL Middleware

Common errors

• Error: Schema must be an instance of GraphQLSchema.

  cause The `applyMiddleware` function received an argument that is not a valid GraphQLSchema object.
  fix Ensure that the first argument passed to `applyMiddleware` is the result of `makeExecutableSchema` or `buildSchema`, or another function that produces a `GraphQLSchema` instance.

• TypeError: Cannot read properties of undefined (reading 'Query') OR Middleware not applied.

  cause This typically occurs when object-based middleware is incorrectly structured, or if middleware functions do not correctly call `await resolve(...)`.
  fix Verify that object-based middleware matches the schema structure (e.g., `Query`, `Mutation`, `Type.field`). For function-based middleware, always include `await resolve(root, args, context, info)` to ensure the next layer or the actual resolver is called.

• Cannot find module 'graphql-middleware' or its corresponding type declarations.

  cause The package is not installed, or TypeScript cannot locate its type definitions.
  fix Run `npm install graphql-middleware` or `yarn add graphql-middleware`. For TypeScript, ensure `tsconfig.json` includes `node_modules/@types` in its `typeRoots` (though usually default) and that the package is correctly installed.

Warnings

• breaking As of v3.0.0, graphql-middleware no longer wraps introspection queries. This means middleware will not run for introspection operations, which might affect security or logging mechanisms that relied on this behavior.
  Fix: If introspection query interception is required, custom logic must be implemented outside graphql-middleware, or an older version (pre-3.0.0) must be used, though this is not recommended due to other potential issues.
• breaking Version 5.0.0 removed out-of-the-box support for GraphQL Yoga. If you are using GraphQL Yoga, you will need to manually integrate graphql-middleware with your Yoga schema, or consider alternatives if direct integration is critical.
  Fix: For GraphQL Yoga users, refer to Yoga's documentation on schema wrapping or custom plugin integration to apply graphql-middleware manually. Older versions might retain direct Yoga support but are not recommended for new projects.
• gotcha Middleware execution follows an 'onion'-like principle: the first middleware in the array is the outermost layer (executed first and last), and subsequent middlewares are inner layers. Incorrect ordering can lead to unexpected behavior.
  Fix: Carefully consider the order of your middleware functions. Middleware that needs to execute before others (e.g., authentication) should be placed earlier in the array passed to `applyMiddleware`.
• gotcha Modifying `args` or `context` objects within a middleware function can lead to side effects in subsequent resolvers or middleware if not managed carefully. Ensure modifications are intended and well-documented.
  Fix: When modifying `args` or `context`, consider immutability patterns where possible (e.g., creating new objects with spread syntax). Test thoroughly to ensure changes don't unintentionally impact other parts of your GraphQL execution flow.

Install

• npm install graphql-middleware npm
• yarn add graphql-middleware yarn
• pnpm add graphql-middleware pnpm

Imports

• applyMiddleware
  wrong:

  const { applyMiddleware } = require('graphql-middleware');

  correct:

  import { applyMiddleware } from 'graphql-middleware';

  The primary function to wrap a GraphQL schema with middleware. Use named import for ESM.
• IMiddlewareFunction

  import { IMiddlewareFunction } from 'graphql-middleware';

  TypeScript interface for defining function-based middleware. Recommended for type safety.
• IMiddleware

  import { IMiddleware } from 'graphql-middleware';

  TypeScript interface for defining object-based middleware, allowing specific field targeting.

Quickstart

Demonstrates how to apply both function-based and object-based middleware to an executable GraphQL schema using Apollo Server, showcasing the 'onion' execution principle and resolver modification capabilities.

import { ApolloServer } from 'apollo-server';
import { makeExecutableSchema } from '@graphql-tools/schema';
import { applyMiddleware, IMiddlewareFunction, IMiddleware } from 'graphql-middleware';

const typeDefs = `
  type Query {
    hello(name: String): String
    bye(name: String): String
  }
`;

const resolvers = {
  Query: {
    hello: (root: any, args: { name?: string }, context: any, info: any) => {
      console.log(`3. resolver: hello`);
      return `Hello ${args.name ? args.name : 'world'}!`;
    },
    bye: (root: any, args: { name?: string }, context: any, info: any) => {
      console.log(`3. resolver: bye`);
      return `Bye ${args.name ? args.name : 'world'}!`;
    },
  },
};

// Function-based middleware for logging input and result
const logInput: IMiddlewareFunction = async (resolve, root, args, context, info) => {
  console.log(`1. logInput: ${JSON.stringify(args)}`);
  const result = await resolve(root, args, context, info);
  console.log(`5. logInput`);
  return result;
};

const logResult: IMiddlewareFunction = async (resolve, root, args, context, info) => {
  console.log(`2. logResult`);
  const result = await resolve(root, args, context, info);
  console.log(`4. logResult: ${JSON.stringify(result)}`);
  return result;
};

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

const schemaWithFunctionMiddleware = applyMiddleware(schema, logInput, logResult);

// Object-based middleware for modifying arguments and results on specific fields
const beepMiddleware: IMiddleware = {
  Query: {
    hello: async (resolve, parent, args: { name?: string }, context, info) => {
      // Override arguments
      const argsWithDefault = { name: 'Bob', ...args };
      const result = await resolve(parent, argsWithDefault, context, info);
      // Modify returned value
      return (result as string).replace(/Trump/g, 'beep');
    },
  },
};

const finalSchema = applyMiddleware(schemaWithFunctionMiddleware, beepMiddleware);

const server = new ApolloServer({
  schema: finalSchema,
});

async function startServer() {
  const { url } = await server.listen({ port: 8008 });
  console.log(`🚀 Server ready at ${url}`);
  console.log('Test queries:');
  console.log('  query { hello(name: "World") }  // Expects "Hello World!" with logging');
  console.log('  query { bye }                   // Expects "Bye world!" with logging');
  console.log('  query { hello(name: "Trump") }  // Expects "Hello beep!" due to middleware');
}

startServer();