The best way to control Claude Code, Codex and more from any computer or phone

main
md 224 lines 7.3 KB
Rendered Raw
1 # Bundle Size Development Workflow
2
3 This package contains the internal bundle-size tooling used to measure Effect
4 entrypoints with Rollup, minification, and gzip.
5
6 ## AI Agent Instructions
7
8 Use this workflow when a user wants to quickly understand how a local source
9 change affects bundle size for one or more explicitly selected fixture files.
10
11 Do not scan `scratchpad/` or `packages/tools/bundle/fixtures/` for this workflow.
12 Only measure files that the user explicitly names, or files you create
13 specifically for the current investigation.
14
15 Use the default cleanup mode. Pass `--keep-base` only when repeated measurements
16 are explicitly requested or clearly necessary, then clean up after the final
17 run.
18
19 If the user asks what a generated bundle is made of, use the bundle composition
20 workflow instead of the size comparison workflow.
21
22 ### Analyze Bundle Composition
23
24 Use this workflow when the user gives an explicit fixture and wants to
25 understand which modules make up the produced bundle.
26
27 Agent procedure:
28
29 1. Confirm the exact fixture path or paths to analyze. Do not scan directories.
30 2. Run `pnpm bundle-analyze` with only those explicit paths.
31 3. Read the printed Markdown table and identify the generated `*.raw-data.json`
32 path for each fixture.
33 4. Analyze `*.raw-data.json` first. Use `*.treemap.html` only when the user wants
34 a visual artifact to open.
35 5. Report the largest modules, notable dependency groups, and any surprising
36 inclusions. Mention the generated artifact paths in the answer.
37
38 Prefer the repository-level wrapper:
39
40 ```sh
41 pnpm bundle-analyze scratchpad/my-fixture.ts
42 ```
43
44 You can pass multiple explicit files:
45
46 ```sh
47 pnpm bundle-analyze \
48 scratchpad/schema-codec.ts \
49 scratchpad/schema-arbitrary.ts
50 ```
51
52 The wrapper builds the current checkout with `pnpm build` before generating
53 analysis artifacts, so the bundle is not produced from stale `dist` files.
54
55 By default, artifacts are written to `tmp/bundle-analysis`. Use `--output-dir`
56 to choose another directory:
57
58 ```sh
59 pnpm bundle-analyze --output-dir tmp/schema-analysis scratchpad/my-fixture.ts
60 ```
61
62 For each selected fixture, the tool writes:
63
64 - `<name>.min.js`: the generated Rollup output for inspection;
65 - `<name>.treemap.html`: an interactive treemap for human inspection;
66 - `<name>.raw-data.json`: raw visualizer data suitable for AI analysis.
67
68 The analysis build disables identifier mangling so module and export names stay
69 readable in the visualizer output. Use `bundle-compare-selected` or `report`
70 when exact size measurement is the goal.
71
72 After running the command, inspect the Markdown table it prints to find the exact
73 paths. For an AI analysis, read the `*.raw-data.json` file first and summarize
74 the largest modules and dependency groups. Use the `*.treemap.html` file when
75 the user wants to inspect the bundle visually.
76
77 The raw data contains a tree plus module metadata. For a quick size-oriented
78 summary, rank module parts by `renderedLength` or `gzipLength`, then map each
79 part through `metaUid` to `nodeMetas[metaUid].id`.
80
81 Example inspection command:
82
83 ```sh
84 node -e 'const data = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8")); console.log(Object.entries(data.nodeParts).map(([uid, part]) => ({ uid, id: data.nodeMetas[part.metaUid]?.id, rendered: part.renderedLength, gzip: part.gzipLength })).sort((a, b) => b.rendered - a.rendered).slice(0, 20))' tmp/bundle-analysis/my-fixture.raw-data.json
85 ```
86
87 Do not treat the generated `.min.js` size from this workflow as the exact bundle
88 size comparison number. The analysis build keeps names readable for the
89 visualizer. Use `bundle-compare-selected` or `report` for exact size reporting.
90
91 Do not use this workflow to compare against a base ref. Use
92 `bundle-compare-selected` for size impact and `bundle-analyze` for current bundle
93 composition.
94
95 ### Compare Explicit Scratchpad Fixtures
96
97 Prefer the repository-level wrapper:
98
99 ```sh
100 pnpm bundle-compare-selected --base main scratchpad/my-fixture.ts
101 ```
102
103 You can pass multiple explicit files:
104
105 ```sh
106 pnpm bundle-compare-selected --base main \
107 scratchpad/schema-codec.ts \
108 scratchpad/schema-arbitrary.ts
109 ```
110
111 If `--base` is omitted, the script compares against `main`.
112
113 By default, the wrapper removes `tmp/bundle-base` before exiting, including on
114 failure. This avoids leaving extra git worktree state after a one-off
115 measurement.
116
117 For repeated measurements where the user explicitly wants a faster feedback loop,
118 pass `--keep-base`:
119
120 ```sh
121 pnpm bundle-compare-selected --base main --keep-base scratchpad/my-fixture.ts
122 ```
123
124 When using `--keep-base`, clean up `tmp/bundle-base` after the last measurement.
125 The explicit final cleanup command is:
126
127 ```sh
128 git worktree remove --force tmp/bundle-base
129 ```
130
131 The wrapper:
132
133 - builds the current checkout with `pnpm build`;
134 - creates or reuses `tmp/bundle-base` at the requested base ref;
135 - builds the base checkout when needed and writes
136 `tmp/bundle-base/.bundle-build-stamp` only after a successful build;
137 - reuses a kept base checkout only when its HEAD and `.bundle-build-stamp`
138 both match the requested base ref;
139 - copies only the selected files into the base checkout at the same relative
140 paths;
141 - invokes the internal bundle CLI to compare current vs base sizes.
142
143 The selected files are copied into the base checkout so the report isolates
144 source changes instead of changes to the fixture text.
145
146 Expected output is a Markdown table:
147
148 ```md
149 | File Name | Current Size | Previous Size | Difference |
150 | :------------------------- | :----------: | :-----------: | :---------------: |
151 | `scratchpad/my-fixture.ts` | 42.10 KB | 40.80 KB | +1.30 KB (+3.19%) |
152 ```
153
154 ### Internal CLI
155
156 Use the internal CLI directly only when the base checkout is already prepared
157 and built:
158
159 ```sh
160 node packages/tools/bundle/src/bin.ts compare-selected \
161 --base-dir tmp/bundle-base \
162 scratchpad/my-fixture.ts
163 ```
164
165 The `--base-dir` value must be the root of the base checkout, not the base
166 fixture directory.
167
168 ### Current Size Only
169
170 If the user only asks for the current bundled size, use:
171
172 ```sh
173 pnpm build
174 pnpm --dir packages/tools/bundle report ../../../scratchpad/my-fixture.ts
175 ```
176
177 Run the build immediately before the report because the direct CLI resolves
178 Effect packages from `dist`. This does not compare against a base ref.
179
180 ### Fixture Guidance
181
182 Keep temporary fixtures in `scratchpad/`.
183
184 Good temporary fixtures are small, focused entrypoints that import public
185 package APIs:
186
187 ```ts
188 import * as Effect from "effect/Effect"
189 import * as Schema from "effect/Schema"
190
191 const schema = Schema.Struct({
192 name: Schema.String
193 })
194
195 Schema.decodeUnknownEffect(schema)({ name: "effect" }).pipe(Effect.runFork)
196 ```
197
198 Prefer self-contained fixtures. The compare-selected workflow copies only the
199 explicit entry files into the base checkout. If a fixture imports local relative
200 helpers, either avoid that shape or make the entry fixture self-contained before
201 measuring.
202
203 Do not add temporary fixtures to `packages/tools/bundle/fixtures/`. That
204 directory is for stable comparison fixtures used by the regular bundle-size
205 workflow.
206
207 ### Cleanup
208
209 The wrapper cleans up `tmp/bundle-base` by default. If `--keep-base` was used for
210 a multi-run investigation, remove the worktree when the user is done.
211
212 To remove it:
213
214 ```sh
215 git worktree remove --force tmp/bundle-base
216 ```
217
218 To verify that cleanup succeeded:
219
220 ```sh
221 git worktree list
222 ```
223
224 Only the main repository worktree should remain.