feat(docsite): document published packages on prod, workspace on canary + PR previews#3858
Merged
Merged
Conversation
The docsite deploys from main to two Vercel targets: production documents the last published npm release; the canary site and every PR preview document the live workspace (main, WIP). The target is derived from VERCEL_ENV — production is 'latest', every other environment is 'canary'. scripts/resolve-content-root.mjs maps the target to the filesystem root the data pipeline reads package docs from: 'latest' downloads the published package tarballs from npm (their src/ ships the .doc.mjs the pipeline needs); 'canary' reads the live workspace. Only documented DATA is pinned — CLI template demos are live-rendered React against the bundled core, so they always come from the workspace. A CanaryBanner (rendered via AppShell's banner slot) warns readers on canary builds and links to production; a footer link cross-links the two sites.
meta-cla
Bot
added
the
CLA Signed
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
the
needs:design-review
github-actions
Bot
requested review from
cvkxx,
ernestt,
kentonquatman and
rubyycheung
July 12, 2026 03:55
josephfarina
approved these changes
Jul 12, 2026
…tent target The latest target materializes each docsite @astryxdesign/* dependency from its published npm tarball, but canaryOnly packages (charts, lab) never publish to the stable latest dist-tag — npm pack failed with ETARGET and broke the production build. Filter the latest package set to stable-publishable packages only, using the same private + astryx.canaryOnly predicate release.yml uses for stable publishing. Those packages still appear on canary, sourced from the workspace.
github-actions
Bot
deleted the
navi/feat/docsite-canary-published-vs-workspace
branch
July 12, 2026 06:57
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
3 participants
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.
Problem
The docsite is deployed from
mainon every push, and its build-time data pipeline reads component docs, props, and package versions straight from the workspace. So the published site always documents work in progress — components and props that only exist onmainshow up in the docs even thoughnpm installdoesn't have them yet. A reader copies an install command, and the thing they just read about isn't in the package.Approach — one codebase, two content lines, keyed off the deploy environment
The docsite code is always current; only the package sources the pipeline reads docs from differ per target:
latestastryx.atmeta.com)canarymain, WIP)The target is derived from Vercel's
VERCEL_ENV: production →latest; every other environment (preview = themaincanary deploy and all PR previews, plus local dev) →canary. No branch-scoped config — an explicitDOCSITE_TARGET/NEXT_PUBLIC_DOCS_TARGEToverride is available for local testing.Content resolution
scripts/resolve-content-root.mjsmaps the target to the filesystem root the pipeline reads from:canary→ the live monorepo workspace.latest→ downloads each docsite@astryxdesign/*dependency's published tarball from npm into a cache laid out like the monorepo (the tarballs shipsrc/, so the.doc.mjsprop tables are present). The pinned version is read live fromnpm view @astryxdesign/core@latest version, so it always tracks the current release with nothing to hand-maintain.generate-data.mjsconsumesCONTENT_ROOTfrom the resolver; every generated registry keeps its exact shape, so no page code changes. Only the documented data is pinned — CLI template demos are live-rendered React that resolve@astryxdesign/corefrom the bundled workspace version, soCLI_ROOTstays on the workspace (pinning it would make a stale release's demo call API the bundled core no longer exposes).UI
bannerslot, shown only on canary builds, linking to the same page on production. Callers gate the slot onCURRENT_TARGET === 'canary'so production renders no banner region at all.Env vars (set in Vercel)
NEXT_PUBLIC_VERCEL_ENVto the client bundle) — required for the banner/footer to know which target they're on.NEXT_PUBLIC_DOCS_LATEST_URL = https://astryx.atmeta.comNEXT_PUBLIC_DOCS_CANARY_URL = https://astryx-canary.vercel.appVerification
pnpm generate(canary) → the fullmaincomponent set (227), reading from the workspace.resolve-content-root.mjsresolvescanary→ workspace andproduction/VERCEL_ENV→latestcorrectly.latesttarball-materialization path needs npm network access, so it's exercised on the Vercel production build rather than in the sandbox.Notes
Supersedes #3513, which mounted canary as a nested static export inside one deployment (
output:'export'+/canarybasePath) and required a raft of page/route rewrites to make the whole app statically exportable. The two-deploy-from-mainmodel needs none of that — both targets are normal server builds — so this PR is a small, self-contained pipeline + UI change.