Fix the Netlify build from the repo and rename document to docs - #815
Merged
Conversation
added 2 commits
August 21, 2026 11:39
The old packages/docs was the v4 documentation and was deleted in 213b4d3; this is the v5 storybook, which had been living under the placeholder name 'document' only to avoid colliding with it. Now that the collision is gone, it takes the name that describes what it is. Renamed the directory, the package name, the root docs:dev / docs:build scripts, the gh-pages artifact path and the storybook MCP server filter in .mcp.json.
…hain The Netlify deploy has failed on every build since June, and deleting packages/docs in 213b4d3 made it unrecoverable: whatever the dashboard build command referenced is gone. Nobody on the team has Netlify credentials, so the fix has to come from the repo — which netlify.toml can do, since it takes precedence over the dashboard. Two likely causes are addressed at once: - pnpm. Overrides live in pnpm-workspace.yaml, which only pnpm 10+ reads; older versions reject the lockfile with ERR_PNPM_LOCKFILE_CONFIG_MISMATCH. Netlify has no PNPM_VERSION variable — the only lever is the root packageManager field via Corepack, which was missing entirely, so Netlify was running whatever pnpm its build image ships. Pinned to 11.22.0, and the inline 'version: 10' is dropped from the three workflows so there is a single source of truth (having both has already produced 'Multiple versions of pnpm specified' on this repo). - build target. command and publish now point at the renamed docs package. base is pinned to '/' to neutralise any stale base directory still set in the dashboard, which would abort the build before this file is read. Node is aligned to 24.x everywhere — it was 20.x in gh-pages and 22.x in the other two — matching the version the suite is developed and tested on locally.
Reverts the trigger removal from e84de92, restoring the original block verbatim, comments included. GitHub Pages is configured with build_type 'workflow' and is already serving commercelayer.github.io/commercelayer-react-components, so the deploy job has a valid target. Note the trigger watches 'main' only, as it originally did: it will stay dormant until v5 lands there. No VITE_BASE_URL is set. packages/docs/.storybook/main.ts reads one, but with it unset Vite emits relative asset paths (./assets, ./sb-manager), which resolve correctly both under the Pages repository subpath and at the Netlify domain root. Verified by inspecting index.html and iframe.html from both builds.
commit: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Brings the Netlify deploy back from the dead and gives the v5 storybook its real name.
Why Netlify was failing
The deploy has errored on every build since June, and deleting
packages/docsin 213b4d3 made it unrecoverable — whatever the dashboard build command pointed at no longer exists. Nobody on the team has Netlify credentials, so the fix has to come from the repo. That works, becausenetlify.tomltakes precedence over the dashboard.Two causes are addressed at once.
pnpm version. Security overrides live in
pnpm-workspace.yaml, which only pnpm 10+ reads; older versions reject the lockfile withERR_PNPM_LOCKFILE_CONFIG_MISMATCH. Netlify has noPNPM_VERSIONvariable — per its docs the only lever is the rootpackageManagerfield via Corepack, and that field was missing entirely, so Netlify was running whatever pnpm its build image happens to ship. It is now pinned topnpm@11.22.0, and the inlineversion: 10is dropped from the three workflows so there is one source of truth (having both has already produced "Multiple versions of pnpm specified" on this repo).Build target.
commandandpublishnow point at the renamed docs package.baseis pinned to/on purpose: a stale base directory left in the dashboard would abort the build before this file is ever read, and that is a scenario nobody can rule out without dashboard access.The whole build config lives in the repo now rather than in the dashboard — the dashboard settings are invisible to code review, which is exactly how this rotted unnoticed for months.
packages/document→packages/docsThe old
packages/docswas the v4 documentation, deleted in 213b4d3. The v5 storybook had been living under the placeholder namedocumentonly to avoid colliding with it; with the collision gone it takes the name that describes what it is. Kept as its own commit so the rename is reviewable on its own.Renamed: the directory, the package
name, the rootdocs:dev/docs:buildscripts, thegh-pagesartifact path, and the storybook MCP server filter in.mcp.json.Toolchain now on latest
11.22.0— verified to keeplockfileVersion: '9.0', so no format break; regenerating changes only the importer block24.xin all three workflows (was20.xin gh-pages,22.xin the other two) and innetlify.toml(was20) — this is the version the suite is developed and tested on locallyVerification
pnpm install --frozen-lockfilepasses under pnpm 11, lockfile unchanged by thepackageManageradditionpnpm buildgreen on all three packages,check-compilerguard includedpnpm test— core-components 110 passed, react-hooks-components 99 passed, react-components 998 passed / 24 skippedpnpm audit --prod --audit-level high— no known vulnerabilitiespnpm docs:buildoutputs topackages/docs/storybook-static, matchingpublishexactlyThe one thing that cannot be verified from here is Netlify itself. The deploy preview on this PR is the first real signal. If it stays red for a reason that lives only in the dashboard — a stale base directory, the wrong production branch, the site linked to the wrong repo — it will need someone with Netlify access.
🤖 Generated with Claude Code