Registry / testing / graphql-schema-diff

graphql-schema-diff

library3.0.0jsnpmunverified

GraphQL Schema Diff is a CLI and library for comparing two GraphQL schemas and detecting dangerous and breaking changes. v3.0.0 (current stable) requires Node 20+, ships TypeScript types, and offers both CLI and JavaScript/TypeScript API. Key differentiators: focused solely on diffing with clear human-readable output, support for remote schema URLs, glob patterns, and HTML output. Unlike GraphQL Inspector which lists all changes, it prioritizes breaking and dangerous detection with exit code configuration.

testing

npm install graphql-schema-diff

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQL-SCHEMA-DIF

graphql-schema-diff

testingjavascriptv3.0.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.

getDiff

✓ import { getDiff } from 'graphql-schema-diff'

✗ const { getDiff } = require('graphql-schema-diff')

ESM-only since v3; require() will throw error.

DiffResult

✓ import { DiffResult } from 'graphql-schema-diff'

✗ const DiffResult = require('graphql-schema-diff').DiffResult

TypeScript type export; also ESM-only.

getDiff (default import)

✓ import graphqlSchemaDiff from 'graphql-schema-diff'

✗ import diff from 'graphql-schema-diff'

No default export exists; use named import.

Compares a remote GraphQL schema URL with a local .graphql file and prints diff with dangerous and breaking changes.

import { getDiff } from 'graphql-schema-diff'; const leftSchema = 'https://swapi-graphql.netlify.app/.netlify/functions/index'; const rightSchema = ` type Query { hero: Character } type Character { name: String! appearsIn: [Episode]! } enum Episode { NEWHOPE EMPIRE JEDI } `; import { writeFileSync } from 'fs'; writeFileSync('./right.graphql', rightSchema); getDiff(leftSchema, './right.graphql', { header: ['Authorization', `Bearer ${process.env.GRAPHQL_TOKEN ?? ''}`], sortSchema: true }).then((result) => { if (!result) { console.log('Schemas are identical!'); } else { console.log('Diff:', result.diff); console.log('Dangerous changes:', result.dangerousChanges); console.log('Breaking changes:', result.breakingChanges); } });

Debug

Known issues

breakinggraphql-schema-diff v3 is ESM-only and requires Node 20+. Using require() will fail.

fix

Use import statements and ensure Node >=20.

affects: >=3.0.0

breakingThe '--input-value-deprecation' flag was added in v3 via graphql-request v6; schemas with deprecated input fields may behave differently when loaded from URL.

fix

Pass --input-value-deprecation if you need deprecated input values included.

affects: >=3.0.0

deprecatedThe 'graphql-schema-diff' CLI global install is deprecated in favor of npx usage.

fix

Use npx graphql-schema-diff instead of global install.

affects: >=3.0.0

gotchaWhen comparing a URL schema with a local file, relative paths are resolved from the current working directory, not the script directory.

fix

Use absolute paths or resolve with path.resolve(__dirname, ...) in API.

affects: >=1.0.0

gotchaThe 'header' option in API expects an array of [key, value] strings, not an object.

fix

Pass headers as ['Authorization', 'Bearer token'].

affects: >=3.0.0

gotchaDiff result can be null if schemas are identical; forgetting to check for null causes TypeError.

fix

Always check if result is falsy before accessing properties.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module 'graphql-schema-diff'

Using CommonJS require() with the ESM-only v3 package.

fix

Switch to ES module imports and ensure package.json has "type": "module" or use .mjs extension.

TypeError: Cannot destructure property 'diff' of 'undefined' or 'null'.

Forgetting to check if getDiff result is null (identical schemas).

fix

Check if result is truthy before destructuring: const result = await getDiff(...); if (result) { const { diff } = result; }

Error: Cannot find module 'graphql-request'

Missing peer dependency graphql-request for schema loading from URL.

fix

Install graphql-request: npm install graphql-request

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/fabsrc/graphql-schema-diff ↗

packagegraphql-schema-diff ↗

homepagehttps://github.com/fabsrc/graphql-schema-diff#readme ↗