copilotkit__copilotkit/dev-docs/bundle-size.md

Bundle Size Tracking

How it works — three tiers

Tier 1: CI (compressed-size-action)

static_bundle_size.yml runs on every PR via preactjs/compressed-size-action (pinned by commit SHA, currently 2.10.0). It scans a glob (packages/{...}/dist/**/*.{mjs,js,cjs}), computes the gzip size of each matched file (the action's default compression; the workflow sets no compression input), and posts a PR comment showing per-file diffs. This step has no hard-fail — no size threshold of any kind (Phase 1). Other steps in the same workflow do fail; see CI behavior.

Fork PRs: pull_request runs triggered from a fork receive a read-only GITHUB_TOKEN, so compressed-size-action cannot post or update the PR comment — it prints the size report to the job logs instead. The measurement still runs; only the comment is unavailable. This is an accepted Phase 1 limitation (the report is informational and carries no size threshold). If the PR comment ever becomes a required signal, switch to a pull_request_target + workflow_run relay pattern so the comment is posted from a trusted context without exposing write tokens to fork code.

Key facts:

• Reports by file path, not by named entry — it does not read .size-limit.json at all.
• The action runs build-script: build (the root build script — nx run-many -t build over all packages/**) on both the PR branch and the base branch, then measures only the files matched by the pattern glob. The root build script is used (rather than a bundle-size-specific one) because the action must build the base branch too, and build exists on every branch. No separate build step is needed before the workflow triggers — the action handles both builds.
• PR comments show paths like packages/react-core/dist/index.mjs (+1.2 kB gzip).

react-native joined the glob in the render-tool convergence (2026-08-06), bringing the glob to 10 packages; its dist/ was previously unmeasured. Separately, pnpm --filter @copilotkit/react-native size:headless (packages/react-native/scripts/measure-headless.mjs, run as the last step of the copilotchat-import-size job) esbuild-bundles the lean import surface of @copilotkit/react-native/headless — deps and all, with react, react-native and react-dom external — and writes the gzipped total (~92 kB today) to the job summary. Like size:headline it is a cross-PR relative signal, not a Metro figure, and it enforces no size budget. It is not silent, though: it exits non-zero on three paths, because the printed number is evidence for a bundle claim.

• The package is not built — assertBuilt checks dist/headless.mjs before esbuild runs, so you get "run the build" instead of a raw resolution stack.
• esbuild fails — errors are re-thrown with context and both errors and warnings are formatted to stderr (logLevel: "silent" stops esbuild printing them itself, so the script must).
• The total is 0, or under MIN_PLAUSIBLE_BYTES (8 kB, ~11x below today's figure) — a plausibility floor, not a budget. A collapsed total means everything got externalized or the dist is empty/stubbed; "0.0 kB" read as a spectacular improvement is the worst way for this to break.

size:headline has the same zero-output guard. So a broken measurement fails the job; only a size threshold is absent — no limit fields, see Phase 2.

The CopilotChat regression signal (job summary, not the PR comment)

The copilotchat-import-size job in static_bundle_size.yml measures what an app importing { CopilotChat } from @copilotkit/react-core/v2 bundles, via packages/react-core/scripts/measure-copilotchat.mjs (run locally with pnpm --filter @copilotkit/react-core size:headline). It drives esbuild directly — bundling { CopilotChat } minified, with react/react-dom external and CSS/fonts stubbed to empty (we measure JS) — and writes the total gzipped JS to the GitHub job summary.

This is a relative regression signal, not a production figure. Its absolute value (currently ~3 MB gzip) is an esbuild number; a real consumer bundler (Vite/Next/webpack) splits eager-vs-lazy differently and reports different absolutes — the Notion "Header Embed Bundle Readout" measured ~386 kB main initial JS under Vite, with the shiki/mermaid language packs as separate generated chunks. The script's worth is consistency: the same measurement every PR, so a change that grows CopilotChat's JS shows up, and the number collapses once OSS-122 moves the language packs to a CDN. A faithful production headline (real Next 15 fixture + @next/bundle-analyzer) is OSS-122 Phase 0.

Why a custom script and not size-limit: CopilotChat pulls katex's CSS, whose url() font refs crash @size-limit/esbuild (which exposes no loader hook). Driving esbuild directly lets us stub the CSS/font assets.

Tier 2: Local dev (size-limit)

The four bundled packages (core, react-core, react-ui, react-textarea) each have a .size-limit.json at their root listing one or more named entries pointing at dist/ paths. Run locally via:

pnpm --filter <pkg> size

The other six packages in the CI glob have no .size-limit.json and no size script (4 + 6 is the 10 packages the workflow's pattern covers):

• shared, runtime-client-gql, web-inspector, voice, a2ui-renderer — unbundled (they emit re-export barrels with separate chunk files); tracked by the CI glob only.
• react-native — multi-entry with every runtime dep external, so the glob measures each entry plus its shared chunks. It has no size-limit config either, but it does ship a bespoke size:headless script (scripts/measure-headless.mjs, an esbuild signal rather than size-limit — see Tier 1 above, including the three paths on which it exits non-zero), run in CI and locally via pnpm --filter @copilotkit/react-native size:headless.

Node version requirement: size-limit@12.1.0 requires Node 20, 22, or 24+ (^20 || ^22 || >=24). Running pnpm --filter <pkg> size on Node 18 will produce an EBADENGINE error.

Tier 3: Structural assertions (hard-fail)

Two checks hard-fail because they assert structure, not a byte threshold — no baseline to maintain, and no conflict with the Phase 2 freeze on limit fields:

1. pnpm --filter @copilotkit/react-core size:assert-headless (packages/react-core/scripts/assert-headless-purity.mjs) — asserts the resolved module graph of the four built React-Native-reachable entry files (dist/v2/headless.mjs / .cjs and dist/v2/context.mjs / .cjs) and fails if shiki, mermaid, cytoscape, katex or streamdown is anywhere in it. Both entries are guarded because @copilotkit/react-native imports both. Runs in static_bundle_size.yml — the step there is named after /v2/headless only, but the script asserts /v2/context as well. Mechanically:

   • It bundles each entry with esbuild (bundle: true, write: false, metafile: true; react / react-dom and the JSX runtimes external; CSS and font assets on the empty loader, which still records them as graph inputs so a CSS-only leak is caught) and reads metafile.inputs — every file esbuild had to load (hundreds of modules; the count is printed per entry on success). Matching runs on those resolved paths, never on file contents, so the walk follows relative chunk edges, exports-map subpaths, extensions and pnpm symlinks on into node_modules.
   • packageNameFor maps each input to its npm package using the last node_modules/ segment (so pnpm's .pnpm/zod@3.25.76/node_modules/zod/lib/index.mjs yields zod, not .pnpm), and isForbiddenPackage matches anchored at the start of that package name — catching the family a dep ships as (@shikijs/langs, cytoscape-fcose) without matching a file that merely mentions the word.
   • Specifiers left external resolve to no graph input, so they are collected separately from each input's imports[].external and matched too.
   • It fails loudly rather than quietly: an edge esbuild cannot resolve throws (an unresolvable edge hides a whole subgraph, so it must never read as clean), a graph that does not contain its own entry throws ("the scan measured nothing"), and esbuild warnings matching will not be bundled or could not be resolved fail the gate instead of being logged. Other esbuild warnings print but are non-fatal — third-party code warns for reasons that say nothing about #4893.
   • The one place it still reads text is to find import(…) / require(…) / require.resolve(…) / __require(…) calls whose argument is not a complete string literal — the one edge shape a bundler genuinely cannot see through — and only in the graph's first-party files. That scan runs over the output of scanSource, a small single-pass tokenizer that blanks comments, strings, templates and regex literals while preserving offsets, so the one surviving regex only ever sees code. A documented counter-example naming a banned dep cannot trip it, a // inside a regex cannot hide a real call, and an argument counts as static only when it is one whole literal with no concatenation or interpolation.
   • Negative tests: packages/react-core/scripts/__tests__/assert-headless-purity.test.mjs, run by pnpm --filter @copilotkit/react-core test:scripts (chained from that package's test). They cover both directions — a forbidden dep reached only through a relative chunk edge (in both an .mjs and a .cjs entry, so the format: "cjs" branch and the require() shape are exercised too), a forbidden dep left external, an unresolvable edge, an unanalyzable loader call, and banned tokens present only in comments and strings, which must pass. Each detector shape fixed in the tokenizer rewrite has a pair: the innocent form must pass and the matching real violation must fail.

2. packages/react-native/src/__tests__/headless-entry-surface.test.ts — walks the relative-import graph of this package's own src/, from both src/headless.ts and src/index.ts, and fails if a reached module imports a react-core entry other than /v2/headless or /v2/context, imports the heavy render stack directly, or (headless entry only) pulls the optional native chat/attachment peer deps. It extracts static import/export … from, bare side-effect import "x", import() and require()/require.resolve() — Metro follows the lazy forms too — strips comments with its own comment/string/template alternation (the purity gate has since moved to the tokenizer described above), reports a non-literal loader argument as unanalyzable rather than ignoring it, and fails loudly on a local edge it cannot resolve. Runs in the normal test job.

What they cover. Between them the two checks catch both shapes of the #4893 regression: react-native importing the fat @copilotkit/react-core/v2 entry (the RN import-graph test), and the heavy render stack being reachable from the lean react-core entries — whether rolldown inlined it or it arrives transitively (the purity gate's graph walk). The transitive hole the earlier substring scan had is closed: react-core's own build leaves @copilotkit/core, @copilotkit/shared, @ag-ui/*, rxjs, zod and uuid external (packages/react-core/tsdown.config.ts), but the purity gate re-bundles with only react / react-dom external, so all of those are resolved and walked.

What they still don't — known limitations. The gate is a real graph assertion, not a complete one. Documented rather than glossed, because a doc that claims a gate is airtight is how the last round of this went wrong:

• The loader-call scan is a tokenizer, not a parser. scanSource classifies every character as code / comment / string / template / regex, which closes the wrong-verdict holes listed in the previous round (a first-character-only literal test, unmatched __require, unstripped string and regex literals, and member calls read as bare loaders — all now covered by paired tests). What remains: regex-vs-division is decided from the previous significant token plus a keyword list, so a regex directly after ) — if (x) /re/.test(s) — is read as division; a misread recovers at the next newline, so its blast radius is one line. No JSX or TypeScript syntax is handled (the targets are built .mjs / .cjs). And indirect loaders are beyond any text scan — aliasing require to another name and calling that, createRequire(…), Function("return import('x')"), or globalThis["im" + "port"].
• Workspace-sibling dist counts as first-party. esbuild resolves pnpm symlinks to real paths, so @copilotkit/core enters the graph as ../core/dist/index.mjs, with no node_modules/ segment. Two consequences: those files are text-scanned for unanalyzable loader calls (a third-party dynamic require that a sibling's bundler inlined can therefore fail this gate), and packageNameFor returns null for them, so a forbidden dep inlined into a sibling's built output contributes no package name and is invisible to the forbidden-list match.
• Only the four .mjs / .cjs entries are targets. UMD builds, declaration files and any other emitted artifact are not asserted.
• Family matching over-reaches slightly: packageName.startsWith("@" + dep) is what catches @shikijs/* and @mermaid-js/*, and it would equally match an unrelated scope such as @katex-something/x. A deliberate trade in the false-positive direction, not an exact match.
• The RN test resolves nothing. It reads only .ts / .tsx files under packages/react-native/src/, records bare specifiers without resolving them, and so sees nothing inside node_modules. Direct-import shape is its job; the transitive one is the purity gate's.

The size:headless esbuild signal (Tier 1) remains what makes a regression's magnitude visible — including for anything that slips through the holes above, since it bundles the real RN entry rather than reasoning about it.

Where configuration lives

.size-limit.json files live at the root of each bundled package (core, react-core, react-ui, react-textarea) and are used exclusively by the local size script. They are not read by CI.

Adding a new measurement

Only bundled packages support local size tracking via size-limit. For the other six packages in the glob, CI covers all chunk files; no local config is needed. Where a specific consumer-facing import needs a number, the pattern is a bespoke esbuild script rather than a .size-limit.json — react-core's size:headline and react-native's size:headless are the two existing examples.

To add a measurement to a bundled package:

1. Add an entry to the package's .size-limit.json:

   { "name": "my-package: MyExport", "path": "dist/index.mjs", "gzip": true }
   

2. Build the package first: pnpm --filter <pkg> build
3. Run locally: pnpm --filter <pkg> size
4. Commit the updated .size-limit.json.

Note: named entries appear in local size-limit output only. CI PR comments report by file path from the glob, not by these names.

Bundled vs. unbundled packages: @size-limit/file reports accurate sizes for bundled packages (those that build a single-file bundle). For unbundled packages (those that emit re-export barrels with separate chunk files), @size-limit/file only counts the barrel file — the CI compressed-size-action glob covers all chunks correctly regardless.

CI behavior (Phase 1 — current)

static_bundle_size.yml posts a comment with per-file gzip diffs on every PR, and that comment carries no size threshold. Sizes today reflect pre-OSS-122 bloat; adding budget limits now would either lock in that bloat permanently or fail immediately on every PR. Neither is useful.

"No hard-fail" is about thresholds only — the workflow does have failing steps. The copilotchat-import-size job fails on the #4893 structural assertion (size:assert-headless, Tier 3) and on either esbuild script reporting a broken measurement (size:headline on zero output; size:headless on an unbuilt package, an esbuild error, or a total under the plausibility floor).

Phase 2 — after OSS-122 (separate ticket, blocked)

Once OSS-122 has reduced the baseline:

1. Add "limit" fields to each .size-limit.json entry.
2. Add a size-limit step to the CI workflow (currently the workflow has no size-limit step — Phase 2 adds one, it does not flip an existing step).
3. PRs that regress past a limit will fail CI.

Do not add "limit" fields before OSS-122 lands.