GraphQL Schema-Driven Codegen: Drift Between SDL and Generated Types

Answer

1️⃣ Pin the SDL: Store a committed snapshot of the server schema (e.g., schema.graphql or introspection.json) and reference it in every code‑gen configuration. This guarantees that local generation always uses the same definition the server currently serves.

2️⃣ Diff before generating: In CI, run a schema‑diff tool (e.g., graphql‑inspector diff or graphql‑schema‑diff) against a fresh introspection from the target environment. A non‑zero diff indicates drift and should block the build.

3️⃣ Deterministic regeneration: Execute the code generator with a fixed configuration and the pinned SDL. Capture a checksum (e.g., SHA‑256) of each generated file or of a bundled hash file.

4️⃣ Checksum comparison: Compare the freshly computed checksums with those committed in the repo. Byte‑identical output is verified when the hashes match; otherwise the CI fails.

Why This Works

• Pinning the SDL removes the “live‑schema” as source of truth; every developer and CI job uses the same file.
• Schema‑diffing catches any server‑side change before codegen runs, preventing stale types from being generated.
• Checksums avoid formatting differences that would otherwise cause a diff to report changes even when the types are semantically identical.
• Pinning tool versions (codegen, diff tool, node/pipenv lockfiles) ensures reproducible output across environments.

CI Steps (example with GitHub Actions)

1. # 1. Fetch live schema
   curl -s -X POST -H "Content-Type: application/json" \
     -d '{"query":"{ __schema { types { name } } }"}' \
     https://api.yourapp.com/graphql \
     > live-introspection.json
   

2. # 2. Diff pinned vs live
   npx graphql-inspector diff schema.graphql live-introspection.json
   # Exit 0 = no drift, non‑zero = drift
   

3. # 3. Regenerate types deterministically
   npx graphql-codegen --config codegen.yml
   

4. # 4. Compute checksums
   sha256sum src/generated/**/*.ts > types.checksum
   # 5. Compare with committed checksum
   diff -u types.checksum.orig types.checksum
   

Missing Detail?

If your CI targets multiple environments (dev, staging, prod) and you want to ensure the same pinned SDL is used across all, confirm that the same schema.graphql file is checked in and referenced in each environment’s code‑gen config.

Practical Verification

Run npx graphql-inspector diff locally against a snapshot of the live introspection you captured from the target environment. If the diff exits cleanly, you can be confident that the SDL and the generated types are in sync before pushing changes.