From ab82fcfc39f7c92604dabb7788bb0e4fbc0e2ed9 Mon Sep 17 00:00:00 2001 From: Paul Hachmang Date: Wed, 20 May 2026 14:22:28 +0200 Subject: [PATCH 1/4] docs: clarify type-check workflow with private packages Spell out that type checking only works per-example, and that any optional/private package must be activated via PRIVATE_ADDITIONAL_DEPENDENCIES (with `yarn install` to link the workspace) and codegen must be re-run before tsgo sees its injected fragments. Documents the three-step workflow that currently fails silently with confusing "field does not exist" errors when skipped. --- .../clarify-typecheck-private-packages.md | 8 ++++ CLAUDE.md | 39 +++++++++++++------ 2 files changed, 35 insertions(+), 12 deletions(-) create mode 100644 .changeset/clarify-typecheck-private-packages.md diff --git a/.changeset/clarify-typecheck-private-packages.md b/.changeset/clarify-typecheck-private-packages.md new file mode 100644 index 0000000000..64109e7dd3 --- /dev/null +++ b/.changeset/clarify-typecheck-private-packages.md @@ -0,0 +1,8 @@ +--- +'@graphcommerce/misc': patch +--- + +Clarify the type-check workflow in CLAUDE.md: type checking is per-example +only, and optional/private packages must be activated via +`PRIVATE_ADDITIONAL_DEPENDENCIES` and codegen must be re-run before `tsgo` +sees their fragments. diff --git a/CLAUDE.md b/CLAUDE.md index a355cc32de..7190c17c16 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -98,18 +98,33 @@ use Playwright: `yarn playwright`. ### Linting & Type Checking -**Important:** For type checking, use `tsgo` (the native TypeScript compiler) -and run it from the **example directory** (not the repo root): - -```bash -# Type check (preferred — fast native TypeScript compiler) -cd examples/magento-graphcms -npx --package=@typescript/native-preview tsgo --noEmit -p . -``` - -Type checking must be run from an example directory because codegen only -generates types for the specific project (`.mesh/`, `.gql.ts` files). Running -from the repo root will fail with missing type errors. +**Important:** You can **only type check an example, never the whole repo**. +Codegen generates types per-example (`.mesh/`, `.gql.ts`) and a private/optional +package's fragments only land in the generated types of an example that +activates the package. Always run `tsgo` from inside an example directory. + +The full workflow for type checking — including any optional/private packages +you want exercised — is: + +1. **Activate the package** by adding it to `PRIVATE_ADDITIONAL_DEPENDENCIES` + in the example's `.env` (comma-separated, no spaces). Yarn workspaces also + needs the package linked, so run `yarn install` from the repo root if the + package is new or hasn't been installed before. +2. **Run codegen** so the package's `.graphql` fragments are injected into the + example's generated `.gql.ts` files: + ```bash + cd examples/magento-graphcms + yarn codegen + ``` +3. **Run `tsgo`** from the same example directory: + ```bash + npx --package=@typescript/native-preview tsgo --noEmit -p . + ``` + +Skipping steps 1–2 produces misleading "field does not exist" errors on +injected fragments, because the example's types still reflect the previously +activated set of packages. Running `tsgo` from the repo root fails for the same +reason — there is no single project-wide type-check, only per-example checks. ```bash yarn eslint:lint # ESLint across all TS/TSX From f0b8e62f5215cb8ec4149ff48d29af9b7c94515e Mon Sep 17 00:00:00 2001 From: Paul Hachmang Date: Wed, 20 May 2026 14:33:47 +0200 Subject: [PATCH 2/4] docs: document cleanup-interceptors + feature-showcase convention Two doc additions: - `graphcommerce cleanup-interceptors` restores `.original.*` files over the codegen-wrapped originals. Always run before committing so dozens of unrelated `next-ui`/`magento-*` wrappers don't pollute the diff. - Every feature PR must include a usage example. For UI components, add a demo route under `packages/demo-magento-graphcommerce/copy/pages/test/` and link it from the test overview; for plugins, wire them into one of the example storefronts so the diff shows the integration point. --- CLAUDE.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 7190c17c16..bbf54ccc1e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -144,6 +144,37 @@ gc-mesh build # Build GraphQL Mesh (merges Magento + Hygraph schemas) gc-gql-codegen # Generate TypeScript from .graphql files → .gql.ts ``` +### Cleaning Up Codegen Interceptors + +Codegen wraps any module that has a matching plugin with an interceptor +(`*.tsx` rewritten to a re-export, original saved as `*.original.tsx`). When +you change `PRIVATE_ADDITIONAL_DEPENDENCIES`, switch branches, or are about to +commit, those wrappers should not end up in `git status`. Restore the +originals with: + +```bash +# Run from any example directory (e.g. examples/magento-graphcms) +graphcommerce cleanup-interceptors +``` + +The command walks every `*.original.*` it finds and restores it back over the +matching wrapped file. **Always run this before committing**, otherwise you +end up with diffs to dozens of `next-ui`, `magento-cart-items`, +`magento-customer`, etc. files that only exist because of your local +`.env`/plugin set. + +### Showcasing New Features + +**Every feature PR must include a working usage of the feature** — a new +component without a page that renders it, or a new plugin without a place +where the host component is rendered, is not reviewable and not validatable. +For pure UI components, add a demo route under +`packages/demo-magento-graphcommerce/copy/pages/test/.tsx` and link +it from `pages/test/[[...url]].tsx`. For plugins, wire them into one of the +example storefronts so the diff shows the integration point. The PR +description's "Test plan" should reference the route or page that +demonstrates the feature. + ### i18n ```bash From 1de133b9e17d220e020be21f9c8415094577adac Mon Sep 17 00:00:00 2001 From: Paul Hachmang Date: Wed, 20 May 2026 14:50:03 +0200 Subject: [PATCH 3/4] docs: a feature showcase means real-storefront integration, not a test route MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Earlier wording suggested adding a `pages/test/.tsx` demo route counted as a showcase. It does not — that route lives outside the real flow, reviewers don't walk through it, and the integration with the storefront stays unproven. Replace the section with a stricter rule: every feature PR must wire the feature into one of the existing example storefronts so it is visible on a real page (product page, account flow, cart page, etc.). The PR's "Test plan" must name the URL the reviewer opens to see it working, and any backend prerequisites (Magento product config, Hygraph content) must be called out. --- CLAUDE.md | 36 +++++++++++++++++++++++++++--------- 1 file changed, 27 insertions(+), 9 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index bbf54ccc1e..85f402a147 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -165,15 +165,33 @@ end up with diffs to dozens of `next-ui`, `magento-cart-items`, ### Showcasing New Features -**Every feature PR must include a working usage of the feature** — a new -component without a page that renders it, or a new plugin without a place -where the host component is rendered, is not reviewable and not validatable. -For pure UI components, add a demo route under -`packages/demo-magento-graphcommerce/copy/pages/test/.tsx` and link -it from `pages/test/[[...url]].tsx`. For plugins, wire them into one of the -example storefronts so the diff shows the integration point. The PR -description's "Test plan" should reference the route or page that -demonstrates the feature. +**Every feature PR must wire the feature into one of the existing example +storefronts so it is visible and presentable on a real page.** A standalone +demo route under `pages/test/*` is **not** a showcase — it lives outside the +real flow, never gets walked by a reviewer, and proves nothing about the +integration. The bar is "if I `yarn workspace @graphcommerce/magento-graphcms +dev` and open the storefront, can I navigate to a place where this feature is +actually used?". + +Concrete patterns by feature kind: + +- **A new UI component** — find the existing page in `examples/magento-graphcms` + (or `examples/magento-open-source`) where it belongs and render it there. A + product video player gets wired into the product page's media gallery, a new + account-menu element into the account layout, a new cart summary block into + the cart page, etc. If the showcase needs backend content (a product with a + YouTube video uploaded, a Magento config flipped on, a Hygraph row created), + call that out in the PR description so the reviewer knows what to configure + before previewing. +- **A new plugin** — wire it where it would actually wrap something, and make + sure the storefront still renders. Activating the package via + `PRIVATE_ADDITIONAL_DEPENDENCIES` is enough wiring as long as the host + component is reachable from a real page in the example. +- **A new GraphQL fragment / mutation** — exercise it from the page or + component that needs the data; don't ship the fragment alone. + +The PR description's "Test plan" must name the storefront URL (or click path) +the reviewer should open to see the feature working. ### i18n From cbe732af473faa6aa3bdde2e38d7d83f9749a0f7 Mon Sep 17 00:00:00 2001 From: Paul Hachmang Date: Wed, 20 May 2026 14:58:32 +0200 Subject: [PATCH 4/4] docs: add hint for recovering a stuck canary release via pre.json --- CLAUDE.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 85f402a147..5f2d002b49 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -244,6 +244,11 @@ Document . `@graphcommerce/misc` (`packagesDev/misc/`) is intentionally empty — it has no consumers, so the published changelog stays clean. +**Stuck release recovery hint:** when a canary publish fails after versions are +already bumped, remove the not-yet-published changeset IDs from +`.changeset/pre.json`'s `changesets` array and push — the next run will +re-consume them and retry the publish. + ## Architecture ### Directory Layout