Registry / security / graphql-rate-limit

graphql-rate-limit

library3.3.0jsnpmunverified

A GraphQL rate limiter library (v3.3.0) that adds basic but granular rate limiting to GraphQL queries and mutations. Works with any Node.js GraphQL setup via three approaches: as a schema directive (@rateLimit), as a graphql-shield rule, or as a base rate limiter function for custom integration. Supports custom stores (Redis, Postgres, Mongo, in-memory default), identity extraction from context, configurable time windows and max requests, and custom error messages. Written in TypeScript, requires Node >=12 and graphql as a peer dependency. Differentiators include simplicity (no complex middleware), flexibility (multiple integration patterns), and first-class TypeScript support.

security

npm install graphql-rate-limit

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQL-RATE-LIMIT

graphql-rate-limit

securityjavascriptv3.3.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

createRateLimitDirective

✓ import { createRateLimitDirective } from 'graphql-rate-limit'

✗ const createRateLimitDirective = require('graphql-rate-limit').createRateLimitDirective

ESM-only package; named export. If using CommonJS, use dynamic import().

createRateLimitRule

✓ import { createRateLimitRule } from 'graphql-rate-limit'

✗ import { createRateLimitRule } from 'graphql-rate-limit/dist/shield'

Named export; not exported from a subpath.

getGraphQLRateLimiter

✓ import { getGraphQLRateLimiter } from 'graphql-rate-limit'

✗ import getGraphQLRateLimiter from 'graphql-rate-limit'

Named export, not default.

Shows how to create a rate limit directive and apply it to a field using @graphql-tools/schema.

import { createRateLimitDirective } from 'graphql-rate-limit'; import { makeExecutableSchema } from '@graphql-tools/schema'; import { gql } from 'graphql-tag'; // 1. Create directive instance with identity extraction const rateLimitDirective = createRateLimitDirective({ identifyContext: (ctx) => ctx.user?.id ?? ctx.ip, }); // 2. Apply to schema const schema = makeExecutableSchema({ typeDefs: gql` directive @rateLimit( max: Int, window: String, message: String, identityArgs: [String], arrayLengthField: String ) on FIELD_DEFINITION type Query { getItems: [String] @rateLimit(window: "10s", max: 5) } `, resolvers: { Query: { getItems: () => ['item1', 'item2'], }, }, schemaDirectives: { rateLimit: rateLimitDirective, }, }); // 3. Use with any GraphQL server (e.g., Apollo Server, Express) export { schema };

Debug

Known issues

breakingidentifyContext is required. If omitted, the rate limiter will throw at runtime.

fix

Always provide identifyContext in instance config.

affects: >=1.0.0

deprecatedThe 'message' field config option is deprecated in favor of custom error formatting via 'formatError' instance config.

fix

Use formatError: (identity, context, fieldConfig) => new Error('Custom message').

affects: >=3.0.0

gotchaThe default store is in-memory and will not persist across server restarts or scale across multiple instances.

fix

For production, provide a custom store (e.g., Redis via ioredis) in instance config.

affects: >=1.0.0

breakinggraphql-rate-limit v3 is ESM-only and no longer supports require().

fix

Use import syntax or dynamic import() in CommonJS projects.

affects: >=3.0.0

Errors

Common errors & fixes

Error: You must provide an identifyContext function.

Missing required 'identifyContext' in instance config.

fix

Add identifyContext: (ctx) => ctx.user?.id ?? ctx.ip when calling createRateLimitDirective, createRateLimitRule, or getGraphQLRateLimiter.

TypeError: rateLimitDirective is not a constructor

Using old graphql-tools syntax where directives are classes, but graphql-rate-limit v3 returns an object.

fix

If using graphql-tools with schemaDirectives, ensure you are using the correct version or use the new schemaTransforms approach.

Cannot find module 'graphql-rate-limit' or its corresponding type declarations.

Package not installed or TypeScript cannot locate types (though types are bundled).

fix

Run 'npm install graphql-rate-limit'. Ensure your tsconfig.json includes 'node' moduleResolution.

Upgrade

Version history

3.3.0latest on npm

Audit

Dependencies

graphqloptionalPeer dependency; required for schema directives and type usage.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/teamplanes/graphql-rate-limit ↗

packagegraphql-rate-limit ↗

homepagehttps://github.com/teamplanes/graphql-rate-limit ↗