Registry / devops / graphql-query-rewriter

graphql-query-rewriter

library3.1.0jsnpmunverified

GraphQL Query Rewriter (v3.1.0) is a library that seamlessly rewrites GraphQL queries in middleware to handle breaking schema changes without requiring client updates. It works with express-graphql and apollo-server, providing rewrite rules for field argument type changes, field renames, argument renames, input field changes, and literal value replacements. Released under MIT license with TypeScript type definitions included. The package is maintained by EF Engineering and has an active development cadence with full API documentation available.

devops

npm install graphql-query-rewriter

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQL-QUERY-REWR

graphql-query-rewriter

devopsjavascriptv3.1.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.

FieldArgTypeRewriter

✓ import { FieldArgTypeRewriter } from 'graphql-query-rewriter'

✗ const FieldArgTypeRewriter = require('graphql-query-rewriter').FieldArgTypeRewriter

The library is ESM-first and includes TypeScript definitions; CommonJS require works but is not the primary pattern.

graphqlRewriterMiddleware

✓ import { graphqlRewriterMiddleware } from 'express-graphql-query-rewriter'

✗ import { graphqlRewriterMiddleware } from 'graphql-query-rewriter'

The middleware is in a separate adapter package; importing from the base package is a common mistake.

Renamer

✓ import { Renamer } from 'graphql-query-rewriter'

Renamer is a base class for custom rewrite rules; it is exported from the main package.

Sets up GraphQL Query Rewriter middleware with express-graphql to transparently rewrite old String! arguments to ID!.

import { FieldArgTypeRewriter } from 'graphql-query-rewriter'; import { graphqlRewriterMiddleware } from 'express-graphql-query-rewriter'; import express from 'express'; import { graphqlHTTP } from 'express-graphql'; import { schema } from './schema'; const app = express(); app.use('/graphql', graphqlRewriterMiddleware({ rewriters: [ new FieldArgTypeRewriter({ fieldName: 'userById', argName: 'id', oldType: 'String!', newType: 'ID!' }) ] })); app.use('/graphql', graphqlHTTP({ schema })); app.listen(4000, () => console.log('Server running on port 4000'));

Debug

Known issues

gotchaThe middleware must be placed BEFORE the GraphQL endpoint in the middleware stack; otherwise the rewrite will not execute.

fix

Ensure app.use('/graphql', graphqlRewriterMiddleware(...)) is called before app.use('/graphql', graphqlHTTP(...)).

affects: >=3.0.0

breakingVersion 3.0.0 changed the way rewriters are configured; the 'rewriters' option is now an array of rewriter instances instead of plain objects.

fix

Migrate from v2-style function rewriters to class instances extending Renamer.

affects: >=3.0.0

deprecatedThe typedef Rector is deprecated in favor of Renamer in v3.0.0.

fix

Replace Rector with Renamer from the main package.

affects: >=3.0.0

gotchaThe package requires Node >=6.0.0 and graphql ^0.12.0 || ^0.13.0 || ^14.0.0; using newer graphql versions (15, 16) may cause incompatibilities.

fix

Upgrade to a version that supports graphql v15/16, or pin graphql to ^14.0.0.

affects: >=3.0.0

gotchaComplex queries with nested variables or fragments may not be fully rewritten; test thoroughly.

fix

Write custom rewriters using Renamer for advanced scenarios.

affects: all

Errors

Common errors & fixes

Cannot find module 'graphql-query-rewriter'

Missing installation of the base package.

fix

npm install graphql-query-rewriter

TypeError: graphqlRewriterMiddleware is not a function

Importing from the wrong package; the middleware is in a separate adapter package.

fix

import { graphqlRewriterMiddleware } from 'express-graphql-query-rewriter';

FieldArgTypeRewriter is not a constructor

Using a plain object instead of an instance of FieldArgTypeRewriter.

fix

Use new FieldArgTypeRewriter({ fieldName: '...', argName: '...', oldType: '...', newType: '...' })

Upgrade

Version history

3.1.0latest on npm

Audit

Dependencies

graphqlrequiredPeer dependency: graphql-js is required for query parsing and manipulation

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/ef-eng/graphql-query-rewriter ↗

packagegraphql-query-rewriter ↗

homepagehttps://github.com/ef-eng/graphql-query-rewriter#readme ↗