Registry / web-framework / graphql-middleware

graphql-middleware

library6.1.35jsnpmunverified

graphql-middleware is a schema wrapper designed to allow developers to compose reusable middleware functions around GraphQL resolvers. This utility enables the execution of arbitrary code both before and after a resolver is invoked, facilitating tasks such as argument modification, result transformation, logging, authentication, and error handling. The current stable version, 6.1.35, demonstrates ongoing maintenance with recent updates focused on bug fixes and dependency compatibility, particularly with newer GraphQL versions. Its release cadence is primarily driven by these maintenance needs rather than frequent new feature introductions. Key differentiators include its intuitive API, which offers complete control over the resolver lifecycle, and its broad compatibility with any standard GraphQL schema, integrating seamlessly with popular GraphQL server implementations like Apollo Server. This library promotes a clear separation of concerns, improving code structure by centralizing cross-cutting logic that would otherwise be duplicated across multiple resolvers. Developers can define middleware at various levels, from global application to specific fields, following an an "onion"-like execution principle.

web-framework http-networking auth-security

npm install graphql-middleware

github ↗package ↗

INSTALL

IMPORT

SIG · GRAPHQL-MIDDLEWARE

graphql-middleware

web-frameworkjavascriptv6.1.35

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

applyMiddleware

✓ import { applyMiddleware } from 'graphql-middleware';

✗ const { applyMiddleware } = require('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.

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();

Debug

Known issues

breakingAs 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.

affects: >=3.0.0

breakingVersion 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.

affects: >=5.0.0

gotchaMiddleware 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`.

affects: >=1.0.0

gotchaModifying `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.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Schema must be an instance of GraphQLSchema.

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.

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.

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.

Upgrade

Version history

6.1.35latest on npm

Audit

Dependencies

graphqlrequiredCore GraphQL library, required for schema definition and execution.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/maticzav/graphql-middleware ↗

packagehttps://www.npmjs.com/package/graphql-middleware ↗