Skip to content

Commit 61a33af

Browse files
ryansolidClaude via Cursorcursoragent
authored
size: measure with Rolldown instead of size-limit/esbuild; re-base caps (#3679)
* size: measure with Rolldown instead of size-limit/esbuild; re-base caps The harness bundled with esbuild because size-limit only offers esbuild or webpack. Rolldown is what Vite ships, so its tree-shaking, chunk shapes and minifier are what applications download: esbuild emitted dead dynamic-import entries and shaped the shared codec chunk by their union (13.0 vs 6.3 KB br for the lazy codec), and minified 4-9% larger on every scenario. - scripts/size/bundle.mjs: Rolldown bundling, real code splitting (lazy chunks reported, never counted), per-module attribution apportioned to the entry chunk's minified length. - size.mjs replaces size-limit as the gate (--json for the PR comment); attribute.mjs ported; report.mjs renders the head-vs-base comment. - .size-limit.js -> scenarios.js: modifyEsbuildConfig hooks become plain alias/external fields; the codec stub (lazy-codec.js) is gone, the page scenarios resolve the real decode entry as a lazy chunk. - Every cap re-based to the Rolldown measurement rounded up to the next 0.01 kB, with a switch note at each limit; floor-caps.json lowered (the freeze check passes without an exception). - size.yml: check job runs size.mjs and uploads its JSON; compare job builds the base branch, measures it with the head's harness (SIZE_PACKAGES_ROOT) and upserts a marker comment, replacing andresz1/size-limit-action. - Rolldown pinned exactly (1.2.11): its minifier decides the numbers. Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> * size: store-hydrating cap from fresh artifacts (30.36 KB) The local dists the re-base measured predated #3674; Linux CI measured the scenario at 30,354 B and a rebuild here agrees to the byte. The other eleven scenarios were identical on both platforms. Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> * size: rebase the Rolldown caps onto next @ ee49b3e Three signals fixes landed since the switch was measured at cad2ce7 (#3678 F3/F5, #3684 F6, #3682 F1); the esbuild ledger notes for them are carried into scenarios.js and every cap is re-measured with Rolldown on the current artifacts, rounded up to the next 0.01 kB: core floor 9506 -> 9508 (9.51 KB, unchanged) + createStore 16504 -> 16584 (16.59 KB) + isPending 12119 -> 12154 (12.16 KB) render + signal 12039 -> 12047 (12.05 KB) hydrating 19606 -> 19623 (19.63 KB) hydrating+stores 30354 -> 30480 (30.48 KB) CSR 14871 -> 14909 (14.91 KB) observe tier 16294 -> 16336 (16.34 KB) observe + attr 30471 -> 30453 (30.46 KB) frames 11768 -> 11768 (11.77 KB, unchanged) page: base 44635 -> 44726 (44.73 KB) page: live 48802 -> 48976 (48.98 KB) All five frozen caps still go down against next's esbuild values, so check-floor-caps passes without an exception. Co-authored-by: Cursor <[email protected]> * size: observe+attr cap 30.46 -> 30.52 KB after #3692 landed on next Rebased onto next @ 656f0df (#3686, #3692 merged). Only the attribution engine scenario moved: 30453 -> 30513 B (+60 B), the #3692 fix on the attribution path. Ledger note added; no frozen floor cap changed. Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> --------- Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]>
1 parent 656f0df commit 61a33af

15 files changed

Lines changed: 683 additions & 683 deletions

File tree

‎.cursor/rules/signals.mdc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ alwaysApply: false
2121

2222
## Changing This Package — Checklist
2323

24-
1. **Bundle size is budgeted.** Scenarios and ratcheted caps live in `scripts/size/.size-limit.js` (run `npm run size` from `scripts/size/` after `pnpm build:js`). Every cap bump needs an audit note there. Restructuring golf is measured NO-WIN (brotli compresses repeats free; indirection adds unique tokens — 2026-09-04 notes). The winning move is **relocation into pay-for-use modules** (e.g. the optimistic module) so floor bundles don't pay.
24+
1. **Bundle size is budgeted.** Scenarios and ratcheted caps live in `scripts/size/scenarios.js`, bundled with Rolldown (run `npm run size` from `scripts/size/` after `pnpm build:js`); the floor and page caps in `scripts/size/floor-caps.json` are frozen. Every cap bump needs an audit note there. Restructuring golf is measured NO-WIN (brotli compresses repeats free; indirection adds unique tokens — 2026-09-04 notes). The winning move is **relocation into pay-for-use modules** (e.g. the optimistic module) so floor bundles don't pay.
2525
2. **Two gates, three tiers.** Checks (strict reads, invariants, forbidden scopes, console reporting, dev-only error text) go under `__DEV__` — dev builds only. Wiring (attribution hook call sites, `_name` labels, graph edge counters, `emitDiagnostic`) goes under `__OBSERVE__` — dev AND the `dist/observe` tier, which production observability consumers select via the `observe` export condition. `__DEV__` implies `__OBSERVE__` (dev.ts asserts it). Prod folds both — free. The observe tier has its own size scenario; the prod scenarios must not move because of it. Public surface: `OBSERVE` (diagnostics channel + the attribution hook slot and interaction frame, observe-legal) vs `DEV` (devtools hooks, graph getters, console face). The attribution ENGINE is the separate `@solidjs/signals/attribution` entry (`src/attribution.ts`; prod resolves the inert `src/attribution.prod.ts`): nothing in the core may import `core/attribution.ts`, or the observe tier ships the engine to consumers that never enable it. Every build has two entries (`index` + `attribution`) sharing one module instance — the flat dev build is code-split for exactly this. Artifacts are ESM only (`dist/prod/`, `dist/observe/`, `dist/dev*.js`; no `.cjs`, no `require` branch): Node >= 22.12 `require()`s ESM, so a CJS host gets the same files — which is why no shipped module may contain a top-level `await` (`tests/dist-artifacts.test.ts` scans for it and `require`s each tier). See `documentation/plans/observe-tier-plan.md`.
2626
3. **Downstream tests consume built dist.** After changing signals, `pnpm --filter @solidjs/signals build` and `pnpm --filter solid-js build` BEFORE running `packages/solid` or `packages/web` tests — stale dist has caused false regression alarms repeatedly.
2727
4. **Facades mirror types.** Store/signal API type changes must be applied in `packages/solid/src/client/hydration.ts` and `packages/solid/src/server/signals.ts` too.

‎.github/workflows/size.yml‎

Lines changed: 61 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,11 @@ name: Size
44
# standalone npm package OUTSIDE the pnpm workspace on purpose: adding its
55
# tooling to the workspace graph re-keys pnpm peer instances (vitest,
66
# @codspeed/vitest-plugin), which relocates the benchmark harness and shows
7-
# up as phantom CodSpeed regressions. The limits in size/.size-limit.js are
8-
# the strict tree-shaking gate; the retained-module-graph assertions in
9-
# packages/signals/tests/treeshake.test.ts stay the which-module
10-
# diagnostic underneath.
7+
# up as phantom CodSpeed regressions. The limits in scripts/size/scenarios.js
8+
# are the strict tree-shaking gate, measured with Rolldown (the bundler Vite
9+
# ships); the retained-module-graph assertions in
10+
# packages/signals/tests/treeshake.test.ts stay the which-module diagnostic
11+
# underneath.
1112
# The check job also runs on direct pushes to next: it is self-contained
1213
# (absolute limits, no base ref), and PR-only triggering let the
1314
# +createStore scenario sit failing at a release commit unnoticed — direct
@@ -47,11 +48,17 @@ jobs:
4748
- run: pnpm build
4849
- run: npm ci --no-audit --no-fund
4950
working-directory: scripts/size
50-
# size-limit gates every scenario against its cap, then attribute.mjs
51-
# prints per-package minified bytes for each so a bump is attributed
52-
# in the same log that reports it.
53-
- run: npm run size
51+
# size.mjs gates every scenario against its cap and prints the lazy
52+
# chunks and per-package minified bytes for each, so a bump is
53+
# attributed in the same log that reports it. The JSON feeds the
54+
# compare job's PR comment.
55+
- run: npm run size -- --json size-head.json
5456
working-directory: scripts/size
57+
- if: always() && github.event_name == 'pull_request'
58+
uses: actions/upload-artifact@v4
59+
with:
60+
name: size-head
61+
path: scripts/size/size-head.json
5562
# The floor and page caps (scripts/size/floor-caps.json) are frozen: a PR
5663
# may lower them, never raise them, unless its body carries a
5764
# `Size-Exception:` line. Compared against the PR's base branch, so
@@ -64,26 +71,60 @@ jobs:
6471
env:
6572
SIZE_EXCEPTION: ${{ github.event.pull_request.body }}
6673

67-
# Best-effort base-vs-head delta comment. Requires the base branch to also
68-
# carry scripts/size/, so it is informational and never blocks: continue-on-error
69-
# keeps bootstrap PRs (and any action hiccup) green. PR events only — the
70-
# action resolves the PR base ref and posts a PR comment, neither of which
71-
# exists on a push event.
74+
# Best-effort base-vs-head delta comment. Builds the base branch and
75+
# measures its artifacts with the HEAD's harness (SIZE_PACKAGES_ROOT), so
76+
# both columns come from the same scenarios and the same Rolldown; the head
77+
# numbers are the check job's. Informational and never blocks:
78+
# continue-on-error keeps bootstrap PRs (and any hiccup) green. PR events
79+
# only — it needs a base ref and a comment target.
7280
compare:
73-
if: github.event_name == 'pull_request'
81+
# always(): the comment is most useful on the PR whose check failed.
82+
if: always() && github.event_name == 'pull_request'
83+
needs: check
7484
runs-on: ubuntu-latest
7585
continue-on-error: true
7686
steps:
7787
- uses: actions/checkout@v4
88+
- uses: actions/checkout@v4
89+
with:
90+
ref: ${{ github.event.pull_request.base.sha }}
91+
path: base
7892
- uses: pnpm/action-setup@v4
7993
- uses: actions/setup-node@v4
8094
with:
8195
node-version-file: ".nvmrc"
8296
cache: pnpm
83-
- uses: andresz1/size-limit-action@v1
84-
continue-on-error: true
97+
- uses: dtolnay/rust-toolchain@stable
98+
- uses: Swatinem/rust-cache@v2
99+
with:
100+
workspaces: base/packages/compiler
101+
- run: pnpm install --frozen-lockfile
102+
working-directory: base
103+
- run: pnpm --filter @solidjs/compiler run build
104+
working-directory: base
105+
- run: pnpm build
106+
working-directory: base
107+
- run: npm ci --no-audit --no-fund
108+
working-directory: scripts/size
109+
- run: node size.mjs --json size-base.json || true
110+
working-directory: scripts/size
111+
env:
112+
SIZE_PACKAGES_ROOT: ${{ github.workspace }}/base
113+
- uses: actions/download-artifact@v4
114+
with:
115+
name: size-head
116+
path: scripts/size
117+
- run: node report.mjs size-head.json size-base.json > size-comment.md
118+
working-directory: scripts/size
119+
- uses: actions/github-script@v7
85120
with:
86-
github_token: ${{ secrets.GITHUB_TOKEN }}
87-
package_manager: npm
88-
directory: scripts/size
89-
build_script: build
121+
script: |
122+
const fs = require("fs");
123+
const body = fs.readFileSync("scripts/size/size-comment.md", "utf8");
124+
const marker = "<!-- size-report -->";
125+
const { owner, repo } = context.repo;
126+
const issue_number = context.payload.pull_request.number;
127+
const comments = await github.paginate(github.rest.issues.listComments, { owner, repo, issue_number, per_page: 100 });
128+
const mine = comments.find(c => c.user.type === "Bot" && c.body.startsWith(marker));
129+
if (mine) await github.rest.issues.updateComment({ owner, repo, comment_id: mine.id, body });
130+
else await github.rest.issues.createComment({ owner, repo, issue_number, body });

‎documentation/plans/size-reduction-audit.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,13 @@ between chunks or out of apps that skip a feature; under this framing it is seco
1616
first-order work is making the code everyone ships smaller with the same semantics: §4.I, the
1717
density audit, comes next.
1818

19+
**Harness switched to Rolldown (2026-09-26, later that night).** Every number in this document
20+
is an esbuild number (size-limit's bundler). The harness now bundles with Rolldown — what Vite
21+
ships — and every cap was re-based; Rolldown lands 4–9% lower on the same artifacts (floor
22+
9,922 → 9,506; base SC page 46,852 → 44,635; live 51,156 → 48,802 at `next` @ cad2ce724; rebased onto ee49b3eee: 9,508 / 44,726 / 48,976). Deltas in the tables here
23+
stay valid as deltas; absolute targets should be read against the Rolldown caps in
24+
`scripts/size/floor-caps.json`.
25+
1926
## 1. Baseline
2027

2128
| Scenario | min | br | signals | solid-js | web | frames | sf |

‎packages/signals/rollup.config.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,7 @@ export default [
8686
tree("dist/prod", false, false),
8787
// Observe tier: the ~40 wiring sites survive (attribution hooks, `_name`,
8888
// edge counters, the diagnostics channel), every check folds out. Selected
89-
// by the `observe` export condition. Gets its own size-limit scenario; the
89+
// by the `observe` export condition. Gets its own size scenario (scripts/size/scenarios.js); the
9090
// prod tree's caps must not move because of it.
9191
tree("dist/observe", false, true)
9292
];

‎scripts/size/README.md‎

Lines changed: 38 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,51 @@
11
# Size scenarios (#2883)
22

3-
Tree-shaken import-cost tracking: `.size-limit.js` defines scenario entries
3+
Tree-shaken import-cost tracking: `scenarios.js` defines scenario entries
44
(signals floor, +createStore, +isPending/latest, the render+one-signal simple
55
app, a representative CSR app, a hydrating pair — with and without store
66
primitives — that keeps the store engine pay-for-use under `hydrate()`, the
77
frames client as a package, and two server-component PAGES: base and live)
8-
with hard brotli limits. CI fails when a scenario exceeds its limit — that
9-
means tree-shaking regressed, or a deliberate feature landed and the limit
10-
should be bumped in the same PR with a reason.
8+
with hard brotli limits on the eager entry chunk. CI fails when a scenario
9+
exceeds its limit — that means tree-shaking regressed, or a deliberate feature
10+
landed and the limit should be bumped in the same PR with a reason.
11+
12+
## Bundler
13+
14+
Scenarios are bundled by **Rolldown** (`bundle.mjs`), the bundler Vite ships
15+
with, so tree-shaking, chunk shapes and the minifier are what an application
16+
actually downloads. Rolldown is pinned exactly in `package.json`: its minifier
17+
decides the numbers, so an upgrade is a re-base recorded like any other cap
18+
change. Code splitting is real — a scenario's `import()` yields a lazy chunk
19+
that is reported and never counted; the seroval codec the page scenarios load
20+
lazily shows up that way at its true size.
21+
22+
Until 2026-09-26 the harness measured with esbuild through `size-limit`. The
23+
switch re-based every cap (Rolldown lands 4–9% lower on the same artifacts;
24+
the table is in the switch PR and each scenario's ledger note in
25+
`scenarios.js`). Ledger deltas must not be read across that line.
1126

1227
## Frozen floor caps
1328

1429
The three floor scenarios — the signals floor, the simple app, and the
1530
hydrating app without stores — and the two server-component page scenarios
16-
have their caps in `floor-caps.json`, not in `.size-limit.js`. They are **frozen**: a PR may lower them, never raise them.
17-
`check-floor-caps.mjs` diffs the file against the PR's base branch in CI and
18-
fails on a raise unless the PR body contains a line starting with
19-
`Size-Exception:` naming why the maintainer accepted the cost. Ten weeks of
20-
individually justified 10–300 B bumps took the signals floor from 7.1 to
21-
9.9 KB; the freeze makes the next one a decision, not a paragraph. See
31+
have their caps in `floor-caps.json`, not in `scenarios.js`. They are
32+
**frozen**: a PR may lower them, never raise them. `check-floor-caps.mjs`
33+
diffs the file against the PR's base branch in CI and fails on a raise unless
34+
the PR body contains a line starting with `Size-Exception:` naming why the
35+
maintainer accepted the cost. Ten weeks of individually justified 10–300 B
36+
bumps took the signals floor from 7.1 to 9.9 KB; the freeze makes the next
37+
one a decision, not a paragraph. See
2238
`documentation/plans/size-reduction-audit.md`.
2339

2440
## Attribution
2541

26-
`npm run size` runs size-limit and then `attribute.mjs`, which bundles every
27-
scenario the same way with an esbuild metafile and prints the minified bytes
28-
each package contributed (`signals`, `solid`, `web`, `web/frames`,
29-
`web/server-functions`, …). Minified bytes are the attributable unit; brotli
30-
compresses across module boundaries. `node attribute.mjs --modules [name]`
31-
lists the individual dist modules of matching scenarios.
42+
`npm run size` (`size.mjs`) gates every scenario and prints, with each result,
43+
the lazy chunks and the minified bytes each package contributed (`signals`,
44+
`solid`, `web`, `web/frames`, `web/server-functions`, …), so a bump is
45+
attributed in the log that reports it. Minified bytes are the attributable
46+
unit; brotli compresses across module boundaries. `node attribute.mjs [name]
47+
[--min bytes]` lists the individual dist modules of matching scenarios.
48+
`node size.mjs --json out.json` writes the results for the PR comment.
3249

3350
## Layout
3451

@@ -38,12 +55,9 @@ changing that graph re-keys pnpm peer instances (vitest,
3855
@codspeed/vitest-plugin), which relocates the benchmark harness and shows up
3956
as phantom CodSpeed regressions. Nothing here is published (`private: true`).
4057

41-
The page scenarios alias the seroval codec to `lazy-codec.js`: both clients
42-
load it through a dynamic import (a separate chunk in production) and
43-
size-limit does not split, so the stub keeps the import site without inlining
44-
the chunk. `lazy-page.js` plays the same role for `lazy()`.
45-
4658
Run locally: `cd scripts/size && npm ci && npm run size` (build the repo
47-
first). The retained-module-graph test in
48-
`packages/signals/tests/treeshake.test.ts` is the companion diagnostic
49-
that names the re-coupled module when shaking breaks.
59+
first). `SIZE_PACKAGES_ROOT=<checkout>` measures another checkout's built
60+
`packages/` with this harness — the compare job uses it for the base branch.
61+
The retained-module-graph test in `packages/signals/tests/treeshake.test.ts`
62+
is the companion diagnostic that names the re-coupled module when shaking
63+
breaks.

0 commit comments

Comments
 (0)