{"id":47939,"library":"graphql-schema-diff","title":"GraphQL Schema Diff","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/fabsrc/graphql-schema-diff","tags":["javascript","graphql","schema","diff","typescript"],"install":[{"cmd":"npm install graphql-schema-diff","lang":"bash","label":"npm"},{"cmd":"yarn add graphql-schema-diff","lang":"bash","label":"yarn"},{"cmd":"pnpm add graphql-schema-diff","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM-only since v3; require() will throw error.","wrong":"const { getDiff } = require('graphql-schema-diff')","symbol":"getDiff","correct":"import { getDiff } from 'graphql-schema-diff'"},{"note":"TypeScript type export; also ESM-only.","wrong":"const DiffResult = require('graphql-schema-diff').DiffResult","symbol":"DiffResult","correct":"import { DiffResult } from 'graphql-schema-diff'"},{"note":"No default export exists; use named import.","wrong":"import diff from 'graphql-schema-diff'","symbol":"getDiff (default import)","correct":"import graphqlSchemaDiff from 'graphql-schema-diff'"}],"quickstart":{"code":"import { getDiff } from 'graphql-schema-diff';\n\nconst leftSchema = 'https://swapi-graphql.netlify.app/.netlify/functions/index';\nconst rightSchema = `\ntype Query {\n  hero: Character\n}\n\ntype Character {\n  name: String!\n  appearsIn: [Episode]!\n}\n\nenum Episode {\n  NEWHOPE\n  EMPIRE\n  JEDI\n}\n`;\n\nimport { writeFileSync } from 'fs';\nwriteFileSync('./right.graphql', rightSchema);\n\ngetDiff(leftSchema, './right.graphql', {\n  header: ['Authorization', `Bearer ${process.env.GRAPHQL_TOKEN ?? ''}`],\n  sortSchema: true\n}).then((result) => {\n  if (!result) {\n    console.log('Schemas are identical!');\n  } else {\n    console.log('Diff:', result.diff);\n    console.log('Dangerous changes:', result.dangerousChanges);\n    console.log('Breaking changes:', result.breakingChanges);\n  }\n});","lang":"typescript","description":"Compares a remote GraphQL schema URL with a local .graphql file and prints diff with dangerous and breaking changes."},"warnings":[{"fix":"Use import statements and ensure Node >=20.","message":"graphql-schema-diff v3 is ESM-only and requires Node 20+. Using require() will fail.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Pass --input-value-deprecation if you need deprecated input values included.","message":"The '--input-value-deprecation' flag was added in v3 via graphql-request v6; schemas with deprecated input fields may behave differently when loaded from URL.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Use npx graphql-schema-diff instead of global install.","message":"The 'graphql-schema-diff' CLI global install is deprecated in favor of npx usage.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Use absolute paths or resolve with path.resolve(__dirname, ...) in API.","message":"When comparing a URL schema with a local file, relative paths are resolved from the current working directory, not the script directory.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Pass headers as ['Authorization', 'Bearer token'].","message":"The 'header' option in API expects an array of [key, value] strings, not an object.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Always check if result is falsy before accessing properties.","message":"Diff result can be null if schemas are identical; forgetting to check for null causes TypeError.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'20':28 'api':38 'break':21,70 'chang':22,67 'clear':46 'cli':9,35 'code':76 'compar':13 'configur':77 'current':24 'danger':19,72 'detect':18,73 'dif':44 'diff':3,6,81 'differenti':40 'exit':75 'focus':41 'glob':56 'graphql':1,4,15,62,79 'html':59 'human':48 'human-read':47 'inspector':63 'javascript':78 'javascript/typescript':37 'key':39 'librari':11 'list':65 'node':27 'offer':33 'output':50,60 'pattern':57 'priorit':69 'readabl':49 'remot':53 'requir':26 'schema':2,5,16,54,80 'ship':29 'sole':42 'stabl':25 'support':51 'two':14 'type':31 'typescript':30,82 'unlik':61 'url':55 'v3.0.0':23","created_at":"2026-06-07T16:54:06.714508+00:00","updated_at":"2026-06-07T16:54:06.714508+00:00","problems":[{"fix":"Switch to ES module imports and ensure package.json has \"type\": \"module\" or use .mjs extension.","cause":"Using CommonJS require() with the ESM-only v3 package.","error":"Cannot find module 'graphql-schema-diff'"},{"fix":"Check if result is truthy before destructuring: const result = await getDiff(...); if (result) { const { diff } = result; }","cause":"Forgetting to check if getDiff result is null (identical schemas).","error":"TypeError: Cannot destructure property 'diff' of 'undefined' or 'null'."},{"fix":"Install graphql-request: npm install graphql-request","cause":"Missing peer dependency graphql-request for schema loading from URL.","error":"Error: Cannot find module 'graphql-request'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/fabsrc/graphql-schema-diff#readme","github":"https://github.com/fabsrc/graphql-schema-diff","docs":null,"changelog":null,"pypi":null,"npm":"graphql-schema-diff","openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}