Add script for TOML config schema doc generation by ryancbahan · Pull Request #6979 · Shopify/cli

ryancbahan · 2026-03-11T20:18:59Z

WHY are these changes introduced?

We need to generate TOML configuration reference docs for shopify.dev. This tooling needs authenticated API calls (appFromIdentifiers, fetchSpecifications) which require the full CLI runtime, so it lives in packages/app and runs via a bin script after pnpm build.

WHAT is this pull request doing?

Adds a new pnpm generate-schema-docs workflow that fetches extension specs from the API and generates doc/interface/example files for all app config sections and extension types:

packages/app/src/cli/services/docs/schema-to-docs.ts — utilities to convert JSON schemas from extension specs into doc-site-compatible TypeScript files (doc pages, interface definitions, example TOML)
packages/app/src/cli/services/docs/generate-schema-docs.ts — generateSchemaDocs(basePath) service function that authenticates, fetches specs, partitions them into app config vs extensions, and writes all output files
bin/docs/generate-schema-docs.js — thin ESM entry point that imports from built dist
bin/docs/build-dev-docs.sh — updated to compile and include config docs alongside command docs when present
bin/docs/tsconfig.schema-docs.json — TypeScript config for compiling the generated .doc.ts files
pnpm generate-schema-docs script in root package.json

Output goes to docs-shopify.dev/configuration/ (doc pages, interfaces, examples) and feeds into the existing build-dev-docs pipeline.

How to test your changes?

pnpm build
Auth with the e2e test app org: pnpm shopify auth login
pnpm generate-schema-docs — produces files in docs-shopify.dev/configuration/
pnpm build-dev-docs — includes config pages in generated output
pnpm knip passes

Measuring impact

n/a - this doesn't need measurement, e.g. a linting rule or a bug-fix

Checklist

I've considered possible cross-platform impacts (Mac, Linux, Windows)
I've considered possible documentation changes

ryancbahan · 2026-03-11T20:19:16Z

Generate TOML configuration schema docs #7040
Add script for TOML config schema doc generation #6979 👈 (View in Graphite)
Add app validate command #6934
main

This stack of pull requests is managed by Graphite. Learn more about stacking.

github-actions · 2026-03-11T20:26:08Z

Coverage report

St.^❔	Category	Percentage	Covered / Total
🟢	Statements	82.03%	14721/17945
🟡	Branches	74.44%	7306/9815
🟢	Functions	81.22%	3727/4589
🟢	Lines	82.44%	13922/16888

Test suite run success

3833 tests passing in 1480 suites.

Report generated by 🧪jest coverage report action from 3e1add3

Adds a new hidden `docs:generate-schema` command that authenticates, fetches all extension specifications, and generates `.doc.ts` files in the `ReferenceEntityTemplateSchema` format for the existing `generate-docs` pipeline. - One consolidated page for app.toml (Global + per-module sections) - One page per extension type - JSON Schema contracts used when available, Zod→JSON Schema fallback via zod-to-json-schema for specs without contracts - Flat dot-notation interfaces for generate-docs compatibility - Build pipeline updated to compile configuration docs if present Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

packages/app/src/cli/services/docs/schema-to-docs.ts

The generate-docs tool overwrites output on each invocation. Schema docs and command docs must be compiled separately (different tsconfigs) but passed to generate-docs together so both end up in generated_docs_data.json. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The service function is imported by bin/docs/generate-schema-docs.js (via dist/), so knip can't trace it from the bin entry. Add it explicitly to the packages/app knip entries. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Reset lockfile to main and re-ran pnpm install to get a minimal diff (only zod-to-json-schema addition). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

These files were accidentally left untracked. The service function contains the logic extracted from the deleted oclif command, and the bin script is the new entry point for pnpm generate-schema-docs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

When merging allOf subschemas, the spread overwrite lost the required array from earlier subschemas. Now required arrays are concatenated, so fields from all subschemas are correctly marked as required in docs. Also add a comment explaining intentional word splitting in build-dev-docs.sh. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Use the existing escapeSingleQuotes helper when emitting enum values in tsTypeForField to prevent syntax errors if a value contains ' or \. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

github-actions · 2026-03-18T21:18:52Z

We detected some changes at packages/*/src and there are no updates in the .changeset.
If the changes are user-facing, run pnpm changeset add to track your changes and include them in the next release CHANGELOG.

Caution

DO NOT create changesets for features which you do not wish to be included in the public changelog of the next CLI release.

ryancbahan · 2026-03-18T21:19:31Z

bin/docs/generate-schema-docs.js

+
+const clientId = process.argv[2]
+if (!clientId) {
+  console.error('Usage: node bin/docs/generate-schema-docs.js <client-id>')


we will need to pass a client id in order to dump extension data until we have a static way to grab schemas without being app-scoped.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

ryancbahan · 2026-03-18T21:25:01Z

packages/app/src/cli/services/docs/schema-to-docs.ts

+    }
+    return {...prop, ...merged, allOf: undefined}
+  }
+  // For anyOf/oneOf, pick the first non-null branch


This may require returning to -- generated docs on pr above this seem good, but the quality of our docgen will be proportional to how straightforward and correct our json contracts are.

ryancbahan mentioned this pull request Mar 11, 2026

Add app validate command #6934

Merged

3 tasks

ryancbahan changed the base branch from rcb/non-interactive-validate to graphite-base/6979 March 18, 2026 15:37

ryancbahan force-pushed the 03-11-add-config-to-docgen branch from 836414a to 553e7c0 Compare March 18, 2026 17:10

ryancbahan force-pushed the graphite-base/6979 branch from 07ccc99 to 2929234 Compare March 18, 2026 17:10

ryancbahan changed the base branch from graphite-base/6979 to main March 18, 2026 17:10

ryancbahan force-pushed the 03-11-add-config-to-docgen branch from 553e7c0 to c48918c Compare March 18, 2026 17:13

github-advanced-security bot found potential problems Mar 18, 2026

View reviewed changes

packages/app/src/cli/services/docs/schema-to-docs.ts Fixed Show fixed Hide fixed

ryancbahan force-pushed the 03-11-add-config-to-docgen branch from c48918c to 33fc9f7 Compare March 18, 2026 17:25

update gen script

80eda46

ryancbahan mentioned this pull request Mar 18, 2026

Generate TOML configuration schema docs #7040

Open

3 tasks

ryancbahan changed the title ~~add docs:generate-schema command for TOML config documentation~~ Move docs:generate-schema from oclif command to standalone bin script Mar 18, 2026

ryancbahan force-pushed the 03-11-add-config-to-docgen branch from 3656b99 to 77b8d03 Compare March 18, 2026 20:07

ryancbahan and others added 4 commits March 18, 2026 14:17

regenerate pnpm-lock.yaml from main

76f7264

Reset lockfile to main and re-ran pnpm install to get a minimal diff (only zod-to-json-schema addition). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix lint: correct import paths and ordering in generate-schema-docs

2a13213

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

ryancbahan changed the title ~~Move docs:generate-schema from oclif command to standalone bin script~~ Add standalone script for TOML config schema doc generation Mar 18, 2026

ryancbahan changed the title ~~Add standalone script for TOML config schema doc generation~~ Add script for TOML config schema doc generation Mar 18, 2026

ryancbahan and others added 2 commits March 18, 2026 15:15

make client ID a required CLI argument instead of hardcoding

8c897e7

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix: escape enum values in generated TypeScript interfaces

4a52b92

Use the existing escapeSingleQuotes helper when emitting enum values in tsTypeForField to prevent syntax errors if a value contains ' or \. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

ryancbahan marked this pull request as ready for review March 18, 2026 21:18

ryancbahan requested review from a team as code owners March 18, 2026 21:18

ryancbahan commented Mar 18, 2026

View reviewed changes

fix comment: developer platform APIs, not Partners API

3e1add3

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

ryancbahan requested review from dmerand and isaacroldan March 18, 2026 21:22

ryancbahan commented Mar 18, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add script for TOML config schema doc generation#6979

Add script for TOML config schema doc generation#6979
ryancbahan wants to merge 11 commits intomainfrom
03-11-add-config-to-docgen

ryancbahan commented Mar 11, 2026 •

edited

Loading

Uh oh!

ryancbahan commented Mar 11, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 11, 2026 •

edited

Loading

Uh oh!

Uh oh!

github-actions bot commented Mar 18, 2026

Uh oh!

ryancbahan Mar 18, 2026

Uh oh!

ryancbahan Mar 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

ryancbahan commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

WHY are these changes introduced?

WHAT is this pull request doing?

How to test your changes?

Measuring impact

Checklist

Uh oh!

ryancbahan commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage report

Test suite run success

Uh oh!

Uh oh!

github-actions bot commented Mar 18, 2026

Uh oh!

ryancbahan Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

ryancbahan Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

ryancbahan commented Mar 11, 2026 •

edited

Loading

ryancbahan commented Mar 11, 2026 •

edited

Loading

github-actions bot commented Mar 11, 2026 •

edited

Loading