All jobs

Add a Bundle Size Check to a TypeScript Library from a Linear Issue

Yes. Label the Linear issue and an agent measures your library's minified gzipped size, sets a limit from that number, and opens a PR with the check wired into CI.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the issue, then how the library is built and shipped. In a package shaped like sindresorhus/ky, package.json is "type": "module" with exports pointing at distribution/index.js and its .d.ts, sideEffects: false, engines.node at 22 or later, and files limited to distribution. The build script is del-cli distribution && tsc --project tsconfig.dist.json, so there is no bundler in the project at all: tsc emits one ES module per source file, 31 of them under source/ across core, errors, types and utils, and consumers' bundlers do the tree shaking. The test script chains xo, the build, a tsc --project tsconfig.test.json pass over test-d and ava. .npmrc sets package-lock=false and .gitignore drops distribution and package-lock.json, so there is no lockfile to update. The readme already shows a bundlephobia minzip badge, which is a number measured after publish, not before merge.

The CI file decides where the check goes. .github/workflows/main.yml runs npm install and npx ava 'test/**' '!test/browser.ts' on macos-latest for Node latest, 24 and 22, and a second job installs Playwright browsers and runs npm test -- test/browser.ts, which is the one that also lints, builds and type-checks. A size check belongs with the build, once, so the agent adds it to that second job after the build step rather than to every Node version in the matrix.

The tool is size-limit with its small-library preset, which bundles the package entry with esbuild, minifies and gzips it, and compares the result to a limit. The agent adds size-limit and the preset as dev dependencies, a size-limit array in package.json with one entry for distribution/index.js as the full import and one for a named import of the default export so a future side effect in a utility module shows up as a jump, and a size script. The limit is a number it measures in the sandbox after npm run build, rounded up with a small margin and stated in the pull request, not a figure from the readme or the badge. xo lints package.json's neighbours and not the config, so no lint rule changes.

It then runs the whole chain the way CI does: npm install, npm run build, npm run size with the measured output kept, then npm test so the ava suite under test/ and the type tests still pass with the new dev dependencies installed. To show the check bites, it adds a scratch import of node:crypto into source/index.ts, runs npm run size again, keeps the failure output, and reverts the change. The pull request description explains that the limit is a ceiling to be raised deliberately in the same commit that justifies it, and shows the one-line command to re-measure.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "A Linear issue labelled agent asks for a bundle size check on this TypeScript library. Read package.json, tsconfig.json, tsconfig.dist.json, .npmrc, .gitignore, readme.md and every workflow under .github/workflows first, and note the entry point in exports, whether a bundler exists, how the build runs and which CI job builds. Add size-limit with the small-library preset as dev dependencies and a size-limit config in package.json with one entry for the package entry point and one for a named import, plus a size script. Run npm install and npm run build, measure the minified gzipped size, and set each limit from the measured number plus a small margin; do not take a number from the readme or a badge. Add the size script to the CI job that already builds, after its build step. Run npm test to confirm the suite still passes. Then add a throwaway import that grows the bundle, show the check failing, and revert it. Open a pull request that links the issue, states the measured sizes and limits, and quotes the passing and failing size output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request on its own branch that changes package.json, adding two dev dependencies, a size-limit array with two entries and a size script, and adds one step to the browser and static checks job in .github/workflows/main.yml. No source file changes, no lockfile appears because .npmrc forbids one, and distribution stays ignored.

The description links the Linear issue, gives a two-row table of the measured size and the limit for each entry, quotes the passing npm run size output from the sandbox and the failing output from the scratch import, and shows the full npm test chain passing with xo, the build, the type tests and ava. It says in one line how to raise a limit when a feature legitimately needs it.

Before merging, a reviewer checks that the margin above the measured size is small enough to catch an accidental dependency but large enough to survive a bug fix, that the check runs after the build step and not before, and that the macOS runner's gzip produces the same number the sandbox did, since zlib builds can differ by a few bytes. Adding a size entry per error class or a comment bot is a follow-up on the same session.

Run it on every Linear issue labelled agent

Sign in to Linear once with POST /me/connections {"type": "app", "name": "linear"} and finish the authorize URL in the console. Then add an automation to the Project with this prompt and a linear trigger on the label you triage with. The trigger adds the issue after the prompt, so a requested ceiling or a second entry point comes from the issue text; the automation's max_runs_per_hour caps how many issues it takes on.

Each labelled issue runs in its own sandbox and opens its own pull request. Once the check exists, a later issue such as the limit is too tight after the retry change runs against the same package.json, re-measures, and moves the number in a one-line pull request with the new measurement quoted.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

Why run it on Rush?

The only honest size limit is one measured on a clean build of the current code, and a library without a bundler has nothing to measure until something bundles it. The agent installs the tool, builds, measures, and proves the check fails when the bundle grows, all in its own sandbox before the pull request exists. A limit copied from a badge would be either already broken or meaninglessly loose.

The record is what makes the number defensible. The transcript shows the build, the measurement, the scratch import and the failure it caused, so a maintainer who thinks the margin is wrong can point at the line and change it in a follow-up with the parked sandbox re-measuring in seconds.

Frequently asked questions

The library has no bundler. What is being measured?

size-limit's small-library preset bundles distribution/index.js with esbuild, minifies it and gzips the result, which is what a consumer's bundler would ship. The measurement happens after npm run build, so it reflects the compiled ES modules, not the TypeScript source.

Where does the limit number come from?

From the sandbox: the agent builds, measures, and sets the limit a little above that figure. The pull request states both numbers. Nothing is taken from the readme badge, which measures a published version, or from memory.

Will this add a lockfile or change xo rules?

No. .npmrc sets package-lock=false and .gitignore already drops package-lock.json, so the install leaves no lockfile, and the size-limit config is a plain field in package.json that xo does not lint.

Why run the check in only one CI job?

The size of the compiled output does not depend on the Node version, so it runs once in the job that already lints, builds and type-checks, after the build step. Adding it to the three-version matrix would triple the work for the same answer.

How do I raise the limit when a feature needs more bytes?

Run npm run build and npm run size, read the measured number from the failure message, and change the limit in package.json in the same commit as the feature, with the reason in the commit message. The pull request description shows that command.

More TypeScript library jobs

The same job on other stacks

Keep reading