2026 04 v1 cleanup

[laurelthorburn]

Part of https://github.com/shop/issues-learn/issues/1601

Background

Same v1 cleanup as #4470, but targeting 2026-04-rc so the older active release branch stops dragging the v1 artifacts.

The v1 generator consumes hand-authored .doc.ts files and emits generated_docs_data.json, generated_static_pages.json, and generated_category_pages.json. We've fully moved to v2, which reads @publicDocs JSDoc tags off the source .ts files and emits generated_docs_data_v2.json. Keeping the v1 files around invites accidental regressions and confuses contributors.

Solution

Scoped to 2026-04-rc (mirror of the cleanup landed on 2026-07-rc in #4470):

• Bump @shopify/generate-docs to 1.2.2 — the latest stable release; v2-only CLI surface.

• Delete all .doc.ts files (~410 files across admin, checkout, customer-account, point-of-sale).

• Delete v1 generated JSONs for 2026-04-rc and surface-level paths: generated_docs_data.json, generated_static_pages.json, generated_category_pages.json.

• Delete v1 type-helper sidecars in src/ that consumed removed exports from generate-docs (ReferenceEntityTemplateSchema, CodeTabType, ExampleType, etc.):

  • src/docs/ (whole tree — component-definitions.ts, docs-type.ts, components/*.ts metadata sidecars)
  • src/surfaces/admin/docs-types.ts
  • src/surfaces/checkout/helper.docs.ts
  • docs/surfaces/checkout/reference/helper.docs.ts

  These were metadata-only files (name/description/category records) consumed exclusively by the deleted .doc.ts files. None of the real component source was touched.

• Slim the four build scripts (admin, checkout, customer-account, point-of-sale) to v2-only:

  • Drop v1-specific flags (--isLandingPage, --isCategoryPage, --typesInput), the transformJson step, .doc.ts → .doc.js tsc compile, and dead template helpers (htmlWrapper, jsxWrapper, etc.).
  • Drop the build-docs-fast.sh / build-docs-watch.sh checkout scripts (v1-only).

• Stop copying screenshots to shopify-dev in every surface's build script.

• Fix build-docs-targets-json.mjs (admin + POS) to locate output dirs via generated_docs_data_v2.json now that generated_docs_data.json is gone.

• Fix buildTargetDts.ts — copyComponentDefinitions now mkdirSync's the components build destination. Previously the dir existed only as a side effect of tsc emitting the now-deleted .doc.ts files; on a clean CI build with no .doc.ts files compiled, copyFileSync failed with ENOENT.

• Fix yarn.lock — the @shopify/generate-docs@1.2.2 resolved URL had been pinned to npm.shopify.io (Shopify's internal registry) because of local .npmrc scope routing. Rewrote it to registry.npmjs.org so CI (which can't auth to the internal mirror) can install. Integrity sha512 is identical between registries.

• Leave scaffolding alone — create-doc-files.js, the gen-docs:admin workspace script, and tsconfig.docs.json are kept since they're authoring tools, not v1 build artifacts.

🎩

• `yarn docs:admin 2026-04-rc`
• `yarn docs:checkout 2026-04-rc`
• `yarn docs:customer-account 2026-04-rc`
• `yarn docs:point-of-sale 2026-04-rc`

Each should produce only `generated_docs_data_v2.json` + `targets.json` under the surface's versioned output dir, with no v1 files anywhere.

CI parity locally (clean `build/` removed first): `yarn lint`, `yarn type-check`, `yarn build`, `yarn test --no-watch` all pass.

Checklist

• I have 🎩'd these changes
• I have updated relevant documentation

[github-actions]

🚨🚨🚨 Docs migration in progress 🚨🚨🚨

We are actively migrating UI extension reference docs to MDX in the areas/platforms/shopify-dev zone of the monorepo. This impacts docs for the following surfaces:

• Admin UI extensions
• App Home
• Checkout UI extensions
• Customer account UI extensions
• POS UI extensions

During this migration, please be aware of the following:

.doc.ts files are being deprecated. Changes to .doc.ts files in this repo will not be reflected in the new MDX-based docs. If you need to update docs for a reference that has already been migrated, make your changes directly in the areas/platforms/shopify-dev zone of the monorepo instead.

Doc comments in .ts source files (the comment blocks above types and functions) are also affected. Generating docs from these comments currently requires a newer version of the @shopify/generate-docs library that isn't yet available. Updates to doc comments may not produce the expected output until the migration is complete.

Examples that previously lived in this repo are being moved to the areas/platforms/shopify-dev zone of the monorepo and should be authored there going forward.

What should I do?

• If your PR includes changes to .doc.ts files, doc comments, or examples, please reach out to us in #devtools-proj-templated-refs so we can help ensure your updates are captured correctly.
• If your PR is limited to source code changes (non-docs), you can ignore this notice.

Thanks for your patience while we complete the migration! 🙏

[jgray7019]

Should these changes be going into 2026-04 branch instead of 2026-04-rc?

[github-actions]

We detected some changes in packages/*/package.json or packages/*/src, and there are no updates in the .changeset directory. If the changes are user-facing and should cause a version bump, run yarn changeset to track your changes and include them in the next release CHANGELOG. If you are making simple updates to repo configuration, examples, or documentation, you do not need to add a changeset.