Skip to content

perf(docsite): keep package README and changelog text out of browser scripts - #13011

Draft
nynexman4464 wants to merge 1 commit into
mainfrom
nynexman4464/perf/docsite-package-registry-text
Draft

nynexman4464 wants to merge 1 commit into
mainfrom
nynexman4464/perf/docsite-package-registry-text

Conversation

@nynexman4464

Copy link
Copy Markdown
Contributor

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/docsite changes.

User or maintainer impact

  • Visitors to the home page, /components and 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.
  • Visitors to the pages that show the text: no change. The package pages (for example /docs/cli) and the changelog pages show the same text. Server components render it, as before.
  • Maintainers: a client module must not import 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, then next start) of main at 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.

Page Viewport Total before Total after Scripts before Scripts after Script text before Script text after
/ 1440 by 900 3,467 KB 2,809 KB 1,702 KB 1,045 KB 6,143 KB 3,785 KB
/ 390 by 844, scale 3, touch 3,442 KB 2,785 KB 1,702 KB 1,045 KB 6,143 KB 3,785 KB
/components 1440 by 900 1,881 KB 1,224 KB 1,695 KB 1,037 KB 5,905 KB 3,547 KB
/playground 1440 by 900 7,732 KB 7,075 KB 6,506 KB 5,850 KB 26,784 KB 24,430 KB
/components/Button 1440 by 900 2,179 KB 2,178 KB 2,000 KB 2,000 KB 7,244 KB 7,244 KB
/docs/cli 1440 by 900 1,479 KB 1,479 KB 1,244 KB 1,244 KB 4,265 KB 4,265 KB
/changelog 1440 by 900 1,004 KB 1,004 KB 625 KB 625 KB 1,783 KB 1,783 KB

"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

  1. Why do browser scripts hold the text? generated/packageRegistry.ts held 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.
  2. Why does that cost so much? The text is 2,339 KB. The changelogs of @astryxdesign/core and @astryxdesign/cli and the README of @astryxdesign/cli are 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.
  3. Which code needs the text? Server modules only: the package page renders a README, and the changelog routes and the sitemap read the changelogs. No client module reads readme or changelog.

Each delta maps to that problem:

Delta Why it is needed
scripts/generate-data.mjs Writes the text to src/generated/packageText.json. PackageMeta loses readme and changelog, so the registry holds metadata only.
src/lib/packageText.ts (new) The typed entry to the text, for server modules.
src/app/(docs)/docs/[topic]/page.tsx, src/lib/changelogData.ts The two readers of the text read it from there.
scripts/check-package-text-bundle.mjs (new), package.json The check, and its place in the build script after next build.
README.md The table of generated files.
src/__tests__/package-text.test.ts (new), src/__tests__/data-extraction.test.ts Three tests pinned pkg.readme and pkg.changelog. They move to the new file and read the text from its new place.
src/__tests__/package-text-bundle-check.test.ts (new) Tests of the check.

Why a JSON file: the check reads the same file that the app reads, with no compile step. searchLinks.json is a generated JSON file in the same directory.

Why a check of the built scripts, and not the server-only package: server-only is 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-033 DEC-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-046 and architecture:knowledge-contracts are linked to these paths. None of their claims covers which generated file holds the text, or what a page's scripts hold.
  • pnpm review:pre lists four claims that the generator and data-extraction.test.ts cite: spec:AST-017 FR21 and FR27 (experimental APIs), and spec:AST-033 FR22 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.
  • No behavior change: each page shows the same text.

Change and evidence

Red, then green. The check, run on the scripts of a production build of main:

Error: A browser script holds package README or changelog text. Only server modules may import src/lib/packageText.ts:
- @astryxdesign/charts README (4 of 4 sampled lines) in 18382-0eb0e0a702ac0137.js
- @astryxdesign/cli README (10 of 10 sampled lines) in 18382-0eb0e0a702ac0137.js
- @astryxdesign/cli changelog (10 of 10 sampled lines) in 18382-0eb0e0a702ac0137.js
- @astryxdesign/core README (10 of 10 sampled lines) in 18382-0eb0e0a702ac0137.js
- @astryxdesign/core changelog (10 of 10 sampled lines) in 18382-0eb0e0a702ac0137.js
  (17 more lines: each README and changelog, in the same script)

In the build of this branch, as a step of pnpm -F @astryxdesign/docsite build:

Package text bundle check passed: 1069 browser scripts hold none of 22 README and changelog texts

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):

Page Visible text
/docs/cli 63,755 characters
/docs/core 2,635 characters
/docs/lab 6,909 characters
/docs/charts 3,584 characters
/docs/richtext 5,089 characters
/docs/vega 13,666 characters
/changelog 136,304 characters
/changelog/cli 226,078 characters
/changelog/cli/2 42,275 characters
/changelog/core/2 160,293 characters
/changelog/richtext 7,006 characters

/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.

  • The visible text of /, /components and /components/Button is the same on both builds. The visible text of /playground is the same on both builds at 1.5, 6 and 12 seconds after the load event.
  • Screenshots of the home page at rest, 5 at 1440 by 900 and 8 at 390 by 844 (scale 3), against a capture of main made 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 of main differ there in the same way.

Scope

Components: docsite generated data

  • This PR has one primary intent.
  • Independently removable deltas were removed or split.
  • Public text and artifacts contain no internal Meta context.

Testing

pnpm -F @astryxdesign/docsite exec vitest run
pnpm -F @astryxdesign/docsite typecheck
pnpm exec eslint --max-warnings 0 <changed files>
pnpm exec prettier --check <changed files>
pnpm build && pnpm -F @astryxdesign/docsite build
pnpm test:docsite-browser
pnpm review:pre --head HEAD
  • src/__tests__/package-text.test.ts (new, 7 tests). The registry has no readme or changelog field. 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.
  • Mutation check: 39 mutations of the changed lines, and each fails a test.
    • 7 in the generator: the text stays in the registry; the README and the changelog swap; a text is missing; the packages are in another order; a package is dropped.
    • 3 in the changelog data, 3 in the package page, and 1 in packageText.ts: the wrong package, the wrong text, or no text.
    • 25 in the check: the threshold, the sampling rules, each character that a minifier can escape, the labels, the files it reads, and the cases with nothing to check.
    • The six lines of the check's command-line entry have no unit test. The build runs them.
  • The docsite unit suite passes: 1,058 passed, 8 skipped. Type check, ESLint and Prettier are clean. pnpm review:pre --head HEAD reports 0 findings.
  • The docsite browser suite on the build of the head: 81 tests, 79 passed. The 2 failures are "failed reachability exposes no internal wording at 390px" (light and dark) in internal-docs-prompt.spec.ts: the afterEach wait 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 of main, 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:

  • The latest docs target. The changed generator lines do not depend on the target, and the data tests run on the canary target.
  • Firefox and Safari. The change has no browser-specific code.
  • The deployed site. All numbers are from local production builds, which compress with gzip.

…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.
@vercel

vercel Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
astryx Ready Ready Preview Nov 19, 2026 9:34pm UTC

Request Review

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Nov 19, 2026
@astracat-bot

astracat-bot Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🟢 Reviewed (for maintainers only) Nov 19, 2026, 9:49 PM UTC

@github-actions github-actions Bot added the needs:design-review Affects visuals — Design should review label Nov 19, 2026
@github-actions

Copy link
Copy Markdown
Contributor

PR Analysis Report

Current run: The current CI run concluded skipped. Current analysis is unavailable.


Generated by PR Enrichment workflow | View current CI run

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 main build 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.json file, server-only is not a dependency, and nothing under packages/ 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: clear
  • apps/docsite/src/lib/packageText.ts: clear
  • apps/docsite/src/app/(docs)/docs/[topic]/page.tsx: clear
  • apps/docsite/src/lib/changelogData.ts: clear
  • apps/docsite/scripts/check-package-text-bundle.mjs: clear
  • apps/docsite/package.json: clear
  • apps/docsite/README.md: clear
  • apps/docsite/src/__tests__/package-text.test.ts: clear
  • apps/docsite/src/__tests__/package-text-bundle-check.test.ts: clear
  • apps/docsite/src/__tests__/data-extraction.test.ts: clear

Automated review (maintainer link)

This branch was successfully deployed

1 active deployment
Preview — ae41401d Deployed Nov 19, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Meta Open Source bot. needs:design-review Affects visuals — Design should review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant