Repository navigation
perf(docsite): keep package README and changelog text out of browser scripts - #13011
Draft
nynexman4464 wants to merge 1 commit into
Draft
nynexman4464 wants to merge 1 commit into
nynexman4464 wants to merge 1 commit into
Conversation
…scripts The package registry held the README and changelog text of each package. Client modules import the registry for a package's name or version, so the text went into a 2.4 MB script that the home page, the components page and the playground load. The generator now writes the text to packageText.json. Only the package page and the changelog data read it, through src/lib/packageText.ts. The build fails when a browser script holds the text.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
AI review status for this pull request.
|
github-actions
Bot
requested review from
cvkxx,
ernestt,
kentonquatman and
rubyycheung
November 19, 2026 21:22
Contributor
PR Analysis Report
Generated by PR Enrichment workflow | View current CI run |
Contributor
There was a problem hiding this comment.
Approved pending CI: CI has not run on this head yet, because the pull request is a draft; it runs once the pull request is marked ready for review.
No blocking findings. The package and changelog pages get the same strings as before, and the new bundle check fails on a build of main, naming all 22 texts in one shared chunk, and passes on this branch's build.
Claims and files checked
Review mode: full; reason: no-earlier-review
- Verified: the package registry no longer carries README or changelog text; a generated JSON file that only server modules import now holds it.
- Verified: the home page, the components page and the playground no longer load the 2.4 MB chunk (about 658 KiB gzip) that held the text; it is in their initial scripts on a
mainbuild and absent on this branch's build. - Verified: the Button, CLI package and changelog pages never loaded that chunk, so this change does not change their scripts.
- Verified: every README and changelog string in the new file equals the old registry's, for the same packages in the same order, so the package pages, changelog pages and sitemap show the same text.
- Verified in substance: "server components render it": server modules read the text and pass one README, or one changelog page, to the client views, as before.
- Verified: client modules import the registry for names, versions and theme lists (the components page, the hero theme reel and the playground themes), and only server modules read the text.
- Verified: the text totals 2,339 KiB, and the core and CLI changelogs and the CLI README are 92.6% of it.
- Verified: the build fails when a browser script holds the text; the check's sampling and threshold work as described, it fails with no scripts or no text, and it checks 22 of 24 texts (one package has no changelog; one 102-byte changelog has no line to sample).
- Verified: the generated JSON follows the existing
searchLinks.jsonfile,server-onlyis not a dependency, and nothing underpackages/changes. - Verified: the record claims that untouched generator and test code cite are not affected.
- Verified: 7 new package-text tests, 17 new check tests, and the docsite unit suite (1,058 passed, 8 skipped) pass; type check and Prettier are clean, and ESLint is clean on the changed code it covers (its config ignores the two scripts).
- Not reproduced: the deployed-site numbers, the screenshot comparison, the mutation run, the pre-review run and the browser-suite result; no record requires them.
apps/docsite/scripts/generate-data.mjs: clearapps/docsite/src/lib/packageText.ts: clearapps/docsite/src/app/(docs)/docs/[topic]/page.tsx: clearapps/docsite/src/lib/changelogData.ts: clearapps/docsite/scripts/check-package-text-bundle.mjs: clearapps/docsite/package.json: clearapps/docsite/README.md: clearapps/docsite/src/__tests__/package-text.test.ts: clearapps/docsite/src/__tests__/package-text-bundle-check.test.ts: clearapps/docsite/src/__tests__/data-extraction.test.ts: clear
This branch was successfully deployed
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
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.
Primary intent
The README and changelog text of each package moves out of the generated package registry, into a generated file that only server modules read. No browser script holds the text.
No other template fits: this is a performance change with no visible change, no new capability, and no public API. Only
apps/docsitechanges.User or maintainer impact
/componentsand the playground: a cold first visit downloads about 657 KB less, and the browser parses about 2,350 KB less script text. The pages look and read the same./docs/cli) and the changelog pages show the same text. Server components render it, as before.src/lib/packageText.ts. The docsite build fails when a browser script holds the text.Bytes for a cold first visit, on local production builds (
next build, thennext start) ofmainat 49473f0 and of this branch. Headless Chromium 149, bytes on the wire from the DevTools protocol, two runs of each page with the same result.///components/playground/components/Button/docs/cli/changelog"Script text" is the size after decompression: what the browser parses. The last three pages did not load the text in a script before, so they do not change.
On the deployed site on 2026-11-19 the script that holds the text was 642 KB of the home page's 3,342 KB on the wire, and 2,186 KB of text.
Problem and solution fit
generated/packageRegistry.tsheld the metadata of each package and the full text of its README and changelog. Client modules import the registry for a package's name, its version, or the list of theme packages: for example the components page, the hero's theme content, and the playground's preview themes.@astryxdesign/coreand@astryxdesign/cliand the README of@astryxdesign/cliare 92% of it. A module is in a chunk as a whole, so each page with a client module that imports the registry loads all of the text: 659 KB on the wire on a local build.readmeorchangelog.Each delta maps to that problem:
scripts/generate-data.mjssrc/generated/packageText.json.PackageMetalosesreadmeandchangelog, so the registry holds metadata only.src/lib/packageText.ts(new)src/app/(docs)/docs/[topic]/page.tsx,src/lib/changelogData.tsscripts/check-package-text-bundle.mjs(new),package.jsonbuildscript afternext build.README.mdsrc/__tests__/package-text.test.ts(new),src/__tests__/data-extraction.test.tspkg.readmeandpkg.changelog. They move to the new file and read the text from its new place.src/__tests__/package-text-bundle-check.test.ts(new)Why a JSON file: the check reads the same file that the app reads, with no compile step.
searchLinks.jsonis a generated JSON file in the same directory.Why a check of the built scripts, and not the
server-onlypackage:server-onlyis not a dependency of this app, and this change adds no dependency. The check also does not depend on how the text gets into a script.No tagalongs, and no public API change: nothing under
packages/is touched.Not in this change: the home page's scripts also hold the generated component registry and blog registry.
Authority
spec:AST-033DEC-1 (product data has one registry-backed owner): the same generator reads the same packages in the same order. It writes the text to a second generated file, and the views still read generated data.spec:AST-033,spec:AST-046andarchitecture:knowledge-contractsare linked to these paths. None of their claims covers which generated file holds the text, or what a page's scripts hold.pnpm review:prelists four claims that the generator anddata-extraction.test.tscite:spec:AST-017FR21 and FR27 (experimental APIs), andspec:AST-033FR22 and FR23 (blog examples and example source). This change does not touch that behavior. It changes the package registry lines of the generator, and it moves three package text tests out of that test file.Change and evidence
Red, then green. The check, run on the scripts of a production build of
main:In the build of this branch, as a step of
pnpm -F @astryxdesign/docsite build:How the check finds the text. It takes up to ten lines of each README and changelog, spread over the text. A line is a sample when it is 40 characters or longer and a minifier does not change it. A script that holds more than half of the samples of a text holds the text. On the build of
main, one script holds every sample of all 22 texts. On the build of this branch, no script holds a sample of any text. The check fails when it finds no script or no text, so it cannot pass with nothing to check. It checks 22 of the 24 possible texts: one package has no changelog, and one changelog is 102 bytes with no line to sample.The pages that show the text still show it. The visible text of each of these pages is the same on both builds (the same length and the same hash):
/docs/cli/docs/core/docs/lab/docs/charts/docs/richtext/docs/vega/changelog/changelog/cli/changelog/cli/2/changelog/core/2/changelog/richtext/sitemap.xml, which lists the changelog pages, is the same on both builds byte for byte (65,465 bytes).No visible change on the pages that gain.
/,/componentsand/components/Buttonis the same on both builds. The visible text of/playgroundis the same on both builds at 1.5, 6 and 12 seconds after the load event.mainmade the same way: 11 are identical pixel for pixel. 1 differs in 54 pixels, by at most 2 of 255. 1 differs where the hero reel shows another slide at the moment of the capture, and two captures ofmaindiffer there in the same way.Scope
Components: docsite generated data
Testing
src/__tests__/package-text.test.ts(new, 7 tests). The registry has noreadmeorchangelogfield. The text lists the packages of the registry in its order, with a README and a changelog where the registry says a package has one. The changelog data gives each changelog route its own package's changelog. The package page gives its view the README of its own package.src/__tests__/package-text-bundle-check.test.ts(new, 17 tests). The check reports a script that holds a README or a changelog, in a nested directory too. It does not report a script that quotes one line, and it reads scripts only. It fails with no scripts directory, no script, or no text.packageText.ts: the wrong package, the wrong text, or no text.pnpm review:pre --head HEADreports 0 findings.internal-docs-prompt.spec.ts: theafterEachwait for network idle timed out. The cause is not in this change: on the same machine that spec alone fails 3 of its 17 tests the same way on the build ofmain, and 2 of 17 on the build of this branch. The machine has no direct route to external hosts. That this is the cause was not confirmed.Not tested:
latestdocs target. The changed generator lines do not depend on the target, and the data tests run on the canary target.