Skip to content

perf(docsite): count the home page's components on the server - #13012

Draft
nynexman4464 wants to merge 1 commit into
mainfrom
nynexman4464/perf/docsite-component-count
Draft

nynexman4464 wants to merge 1 commit into
mainfrom
nynexman4464/perf/docsite-component-count

Conversation

@nynexman4464

Copy link
Copy Markdown
Contributor

Primary intent

The docs home page gets the number of components from its server entry. Its scripts no longer hold the component registry, which the page loaded only to count entries.

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: a cold first visit downloads 403 KB less, and the browser parses 1,700 KB less script text. The page looks and reads the same.
  • Visitors to other pages: no change. /components, a component page and the playground render from the registry in the browser, and still load it.
  • Maintainers: a client module that the home page loads must not import generated/componentRegistry. A browser test fails when one does.

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 3,064 KB 1,702 KB 1,300 KB 6,143 KB 4,443 KB
/ 390 by 844, scale 3, touch 3,442 KB 3,040 KB 1,702 KB 1,300 KB 6,143 KB 4,443 KB
/components 1440 by 900 1,881 KB 1,881 KB 1,695 KB 1,694 KB 5,905 KB 5,905 KB
/components/Button 1440 by 900 2,179 KB 2,178 KB 2,000 KB 2,000 KB 7,244 KB 7,244 KB
/playground 1440 by 900 7,732 KB 7,740 KB 6,506 KB 6,514 KB 26,784 KB 26,802 KB

"Script text" is the size after decompression: what the browser parses. The home page makes 138 requests in place of 140.

The playground loads 8 KB more. With the registry out of the home page, webpack groups a few shared modules into other chunks, and the set that the playground loads comes out 18 KB larger before compression. No code of the playground changes.

On the deployed site on 2026-11-19 the registry script was 320 KB of the home page's 3,342 KB on the wire, and 1,414 KB of text.

Problem and solution fit

  1. Why does the home page load the registry? FeaturesShowcase and DiscoverShowcase are client components. Each imported components from generated/componentRegistry and counted the public Core components when the module loaded, for the copy "Over 190 components" and "Browse 190+ components".
  2. Why does that cost so much? The registry holds the props, usage notes, theming notes and type declarations of every component: 1.7 MB after minification. A client module that imports it puts all of it into a script of each page that loads the module.
  3. Why does it matter? The registry script is 404 KB of the home page's 3,467 KB, and the browser parses 1.7 MB of text to get one number.

Each delta maps to that problem:

Delta Why it is needed
src/app/(site)/page.tsx The page's server entry counts the public Core components, with the expression that the two client components used, and gives HomePage the number as coreComponentCount.
src/app/(site)/HomePage.tsx Gives the number to the two sections that show it.
src/app/(site)/_landing/FeaturesShowcase.tsx Takes the number as a prop. The components card gets its title where the card renders, so the features map types that one entry without a title.
src/app/(site)/_landing/DiscoverShowcase.tsx Takes the number as a prop.
src/__tests__/home-component-count.test.tsx Pins the count that the server entry computes, and the copy of the two sections.
e2e/home-component-registry.spec.ts Fails when the built home page loads a script that holds the registry, or when one of the two places shows another number.

The count is the same expression as before: the Core components that are not hidden and are not hooks, rounded down to the nearest 10. It is 190 on both builds.

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 package registry and blog registry.

Authority

  • spec:AST-033 DEC-1 (product data has one registry-backed owner): the number still comes from the generated registry, and no page owns a count of its own. The count moves from two client modules to the page's server entry.
  • spec:AST-033 and architecture:knowledge-contracts are linked to apps/docsite/**. None of their claims covers which module counts the components, or what a page's scripts hold. pnpm specs:for --diff origin/main routes no concern claim to the added lines.
  • No behavior change: the page shows the same copy with the same number.

Change and evidence

Red, then green. The new browser test on a production build of main:

  ✘  1 e2e/home-component-registry.spec.ts:83:5 › the home page loads no script that holds the component registry
  ✓  2 e2e/home-component-registry.spec.ts:105:5 › the home page shows the count of the registry on the components card and in the closing section

    Error: expect(received).toEqual(expected) // deep equality

    - Array []
    + Array [
    +   "/_next/static/chunks/25734-23ecb15c38b51759.js",
    + ]

On the build of this branch both tests pass.

How the test finds the registry. It takes ten component descriptions, spread over the generated registry, in a form that a minifier does not change. A script that holds more than half of them holds the registry. The test first loads /components and expects to find such a script there, so a registry that the samples cannot find fails the test and does not pass it.

No visible change.

  • The second browser test passes on main and on this branch: the components card says "Over 190 components" and the closing section says "Browse 190+ components".
  • The visible text of / is the same on both builds (5,242 characters, the same hash).
  • Screenshots of the whole 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: 12 are identical pixel for pixel. 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.

The server and client boundary, in a real build. page.tsx is a server component and gives HomePage, a client component, a number. pnpm -F @astryxdesign/docsite build passes, and the page hydrates with no error (the existing home-late-script browser tests pass).

Scope

Components: docsite home page

  • 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__/home-component-count.test.tsx (new, 3 tests). The server entry's count, against a registry fixture in which a wrong filter, a wrong package or a wrong rounding gives a number in another ten. The copy of the components card and of the closing section, for a number that they receive.
  • e2e/home-component-registry.spec.ts (new, 2 tests). The first is described above. The second proves that the built page shows the count on the components card and in the closing section: the unit test cannot see what HomePage gives the two sections.
  • Mutation check: 16 mutations of the changed lines.
    • 13 fail a unit test: the count includes hidden components, hooks, or every package; it rounds up, to the nearest, not at all, or to 100; the entry gives the page another number; a section shows another number or a fixed one.
    • 3 need a build, and each fails a browser test on a production build of the mutant: HomePage gives the components card another number; HomePage gives the closing section another number; a client component of the home page imports the registry again.
  • The docsite unit suite passes: 1,040 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: 83 tests, 79 passed. The 4 failures are the four "failed reachability exposes no internal wording" cases of 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:

  • A script that the home page loads after its network is idle. The browser test reads the scripts that the page loads before that.
  • Firefox and Safari. The change has no browser-specific code.
  • The deployed site. All numbers are from local production builds, which compress with gzip.

Two client components of the home page imported the component registry to
show "Over 190 components". The registry holds the documentation of every
component, so the page loaded a 1.7 MB script to count its entries.

The page's server entry now counts the public Core components and gives
the page the number. A browser test fails when the home page loads a
script that holds the registry.
@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:35pm 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:40 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. Moving the component count into the home page's server entry keeps the same registry-derived number and copy, and the new unit and browser tests pin both. Next step: mark the pull request ready for review so CI runs the docsite build and the new browser test.

Claims and files checked

Review mode: full; reason: no-earlier-review

  • Claim: the home page takes its count from its server entry and its client scripts no longer import the component registry. Verified: page.tsx imports and counts it (lines 13, 20-25); neither section imports it; no client module of the home page imports it as a value.
  • Claim: only the docsite app changes, with no public API change. Verified: all six files are under apps/docsite.
  • Claim: a cold home-page visit downloads about 403 KB less and parses about 1,700 KB less script, in 138 requests instead of 140. Not reproduced (local build measurements); consistent with the removed client imports.
  • Claim: other pages are unchanged, and the playground grows 8 KB from chunk regrouping. Not reproduced; no code of those pages changes.
  • Claim: the base loaded the registry because both client sections imported it to count. Verified in the base sources.
  • Claim: the registry is about 1.7 MB minified. Not reproduced; the generated source is about 2.4 MB.
  • Claim: the count uses the same expression and is 190. Verified: the expression is unchanged, and the head's registry has 191 public Core components.
  • Claim: the package and blog registries still ship on the home page. Verified (hero content and blog showcase imports).
  • Claim: the docsite product-data decision still holds and no linked claim decides which module counts. Verified against the current docsite contract.
  • Claim: the spec routing tool routes no concern claim to the change. Consistent: the global-baseline router returns no concern match.
  • Claim: no visible change. Verified for the copy by the code and the unit test; screenshot and text-hash comparisons not reproduced.
  • Claim: the browser test fails on main and passes on this branch. Not reproduced; the failing line numbers match the head spec.
  • Claim: the browser test detects the registry with ten description samples and checks them on /components first. Verified by reading (218 eligible descriptions, 10 distinct samples).
  • Claim: the server page passes a number to the client HomePage. Verified.
  • Claim: the unit test has 3 tests and its fixture separates a wrong filter, package or rounding. Verified: it passes 3 of 3, and each listed mutation changes the fixture's answer.
  • Claim: 16 mutations were checked. Not reproduced.
  • Claim: the docsite unit suite, type check, ESLint, Prettier and the pre-review check are clean. ESLint and Prettier clean on the six files; type check shows no new error against the base with packages unbuilt; the full suite and pre-review check not run.
  • Claim: the browser suite passed 79 of 83, the 4 failures unrelated. Not reproduced; CI has not run.
  • Claim: late scripts, Firefox, Safari and the deployed site are untested. Accepted as stated; the test reads scripts loaded before network idle.
  • File apps/docsite/src/app/(site)/page.tsx: clear.
  • File apps/docsite/src/app/(site)/HomePage.tsx: clear.
  • File apps/docsite/src/app/(site)/_landing/FeaturesShowcase.tsx: clear.
  • File apps/docsite/src/app/(site)/_landing/DiscoverShowcase.tsx: clear.
  • File apps/docsite/src/__tests__/home-component-count.test.tsx: clear.
  • File apps/docsite/e2e/home-component-registry.spec.ts: clear (runs in CI).

Automated review (maintainer link)

This branch was successfully deployed

1 active deployment
Preview — 2a29f844 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