All jobs

Add a Bundle Size Check to a Lit Component

Yes. An agent adds size-limit to your Lit component, measures its gzip cost with and without lit, sets budgets just above them, reports on each PR and opens a PR.

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

What the agent does

In a package like lit/lit-element-starter-ts, the agent reads package.json: @lit/lit-starter-ts 2.0.3 with lit ^3.2.0 as its only dependency, build running tsc with rootDir of src and outDir of the package root, so the published module is my-element.js next to package.json, and a checksize script that already exists: rollup -c ; cat my-element.bundled.js | gzip -9 | wc -c ; rm my-element.bundled.js. rollup.config.js bundles my-element.js to my-element.bundled.js as ESM with @rollup/plugin-node-resolve, a replace of Reflect.decorate with undefined, terser mangling properties that start with __, and rollup-plugin-summary; .gitignore lists the bundled file as "only generated for size check". The README says that setup serves the docs site and recommends publishing unoptimized modules and optimizing at the application level. Tests run on @web/test-runner with Playwright in dev and prod modes, lint runs lit-analyzer and ESLint, and the starter has no .github directory.

The check should measure what a consumer pays, which the README's advice makes two numbers: the component alone, and the component with lit resolved and tree-shaken. The agent adds size-limit with @size-limit/preset-small-lib, which bundles with esbuild and reports gzip size, and a size-limit array in package.json with two entries on path: my-element.js: one named for the component with lit, and one with ignore: ["lit"] for the component's own code. Each entry's limit is set from a measurement the agent takes in its sandbox, a little above the number it read, so the first run passes and a change that pulls in a directive bundle or a second copy of a dependency fails. A size script runs size-limit, and checksize stays, since the rollup path and the esbuild path are useful to compare and the README refers to the rollup setup.

The agent adds .github/workflows/size.yml on pull_request: checkout, actions/setup-node with npm caching, npm ci, npm run build, because my-element.js is generated by tsc and does not exist in a fresh checkout, and npx size-limit, which fails the job over either budget. For the number in the pull request conversation it uses andresz1/size-limit-action with build_script set to build and pull-requests: write, so the action builds the base branch too and comments both sizes and the delta on every pull request. Playwright is not installed for this job; the test workflow, where one exists, is unchanged.

To verify, the agent runs npm ci, npm run build, npx size-limit --json and npm run checksize in its sandbox and pastes all three, explaining why the esbuild and rollup numbers differ by a little. It then adds a deliberate import of a large module to src/my-element.ts, runs the check again to show it fails with the overage printed, and reverts. The size-limit field, the two devDependencies and the workflow are the whole change; custom-elements.json, the docs site under docs-src and the tests are untouched.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Add a bundle size check to this Lit component package. Read package.json, tsconfig.json, rollup.config.js, .gitignore, README.md and src/my-element.ts first, and note that the component's module is built by tsc. Use size-limit with the small-library preset and configure two entries on the built module: the component with its lit dependency resolved, and the component alone with lit ignored. Measure both in your sandbox and set each limit a little above what you measured. Add a size script, keep the existing checksize script, and add a workflow that builds and runs the check on every pull request and comments the sizes and the change against the base branch. Show the check failing on a deliberate heavy import, then revert it. Open a pull request with the measurements.",
  "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

The pull request changes package.json and package-lock.json and adds .github/workflows/size.yml. Its description pastes the size-limit output for both entries, the checksize number beside them, the two budgets with how far above the measurement each sits, and the failing run from the deliberate heavy import.

The new size workflow runs on the pull request itself and leaves a comment with the component's size with and without lit and a zero change against the base, so a reviewer sees the check working before merging it. The run's record keeps the sandbox measurements and the reverted experiment.

Before merging, a reviewer sets the budgets where the team wants them, decides whether the component-only entry is worth keeping for a package this small, and whether the check should also run on pushes to the default branch. The component, the tests and the docs build are unchanged.

Run it on every pull request

Once the workflow is merged the measurement runs on every pull request with no further agent involved: the action builds the base branch and the head, prints both sizes, and the job fails over budget. An automation on the Project with a github trigger on pull_request.opened and pull_request.synchronize and the prompt "if the size check failed on this pull request, find the import that added the bytes and suggest a lighter way to do the same" turns a red check into a specific suggestion; the trigger adds the pull request after the prompt, and only work by an owner, member or collaborator fires it.

For a team with many component packages, the same body goes to POST /o/{org}/sessions once per repository with a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run measures its own package and sets its own budgets; a monorepo gets one size-limit entry per package. The key's webhook_url reports each run the key starts with the pull request in result.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

A size budget is only honest if it was measured on the real module with the real dependency graph, and for a Lit component that means building with tsc first and deciding whether lit counts. The agent reads the README's publishing advice, measures both numbers in its own sandbox, sets budgets from what it saw, and proves the check fails by making it fail once.

The measurements, the failing experiment and the first workflow comment stay with the run and are quoted in the pull request. A team with a family of component packages gets a check per repository, each with budgets from that package's own numbers.

Frequently asked questions

Why two entries, with and without lit?

The README recommends publishing unoptimized modules and letting the consuming application optimize, so a consumer who already uses lit pays only for the component's own code, while one who does not pays for lit too. Measuring both shows which of the two a change moved; a new directive import grows the first, a heavier render grows both.

Why size-limit when checksize already exists?

checksize prints one number from a rollup bundle and nothing compares it to anything. size-limit holds the budgets in package.json, fails the job over them, and its action comments the delta against the base branch on each pull request. The agent keeps checksize since the rollup setup is also used for the docs site.

How were the budgets chosen?

From the agent's own measurement in the pull request, each set a little above the number it read so the first run passes and a real regression fails. The description shows the margin; a reviewer who wants a tighter or looser budget changes one string in package.json.

Does the workflow need Playwright?

No. The size job runs npm ci, tsc and size-limit, which bundles with esbuild and needs no browser. The test workflow that installs Playwright for @web/test-runner, where the repository has one, is unchanged.

More Lit jobs

The same job on other stacks

Keep reading