# Add an npm Release Workflow to a Lit Component

Yes. An agent makes a Lit element publishable, adds a tag-triggered GitHub Actions workflow that builds, tests and publishes to npm with provenance, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-release-workflow/lit/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

Publishing a web component is mostly about what goes in the tarball, so the agent reads `package.json` before any workflow. In a project laid out like lit/lit-element-starter-ts, the package is `@lit/lit-starter-ts` at version `2.0.3` with `"private": true`, `"type": "module"`, and `main` and `module` both pointing at `my-element.js`, the file `tsc` emits from `src/my-element.ts` because `tsconfig.json` sets `rootDir` to `./src` and `outDir` to `./` with `declaration`, `declarationMap` and `sourceMap` on. `.gitignore` ignores that emitted `my-element.js`, its `.d.ts`, both map files, `/test/` and `custom-elements.json`, so none of the build output is in git. The scripts are `build` (`tsc`), `lint` (`lit-analyzer` then `eslint`), `test` (`wtr` in dev and prod mode through `@web/test-runner` with the Playwright launcher), `analyze` (`cem analyze --litelement` into `custom-elements.json`, which `"customElements"` already names) and `checksize`. The only dependency is `lit` `^3.2.0`. There is no `.github` directory at all, and `CHANGELOG.md` is in changesets format with entries for `2.0.3`, `2.0.2` and `2.0.1`.

The agent makes the package publishable first. It removes `"private": true`, adds `"files"` listing `my-element.js`, `my-element.d.ts`, both maps, `src/my-element.ts` and `custom-elements.json` so the eleventy `docs/` site, `dev/` and the rollup config stay out of the tarball, adds an `"exports"` map with `"."` pointing at `./my-element.js` with its `types`, a `"publishConfig"` of `{"access": "public"}` for the scoped name, and a `"prepack"` script that runs `build` and `analyze` so `npm pack` and `npm publish` always ship fresh output. `"sideEffects"` is set to the module file, because registering a custom element with `@customElement('my-element')` is a side effect bundlers must keep. The README's note that the component is published as unoptimized modules, with bundling left to the consuming app, matches this shape, and the agent quotes it in the pull request.

Then it writes `.github/workflows/release.yml`, triggered on `push` of tags matching `v*`. The job sets `permissions` to `contents: read` and `id-token: write`, checks out, runs `actions/setup-node` with Node 22 and `registry-url: https://registry.npmjs.org`, runs `npm ci`, `npx playwright install --with-deps chromium` so the Web Test Runner's Playwright launcher has a browser, then `npm run lint`, `npm test` and `npm run build`, and finally `npm publish --provenance --access public`. A guard step compares the tag to `package.json`'s `version` and fails the job when they differ, so a mistyped tag never publishes the wrong number. The workflow prefers npm trusted publishing, where the package on npmjs.com is linked to this repository and workflow and no token is stored; the pull request also shows the one-line change to use an `NPM_TOKEN` secret for a registry that is not set up for it.

Before opening anything, the agent checks the tarball in its sandbox: `npm ci`, `npm run build`, `npm run analyze`, then `npm pack --dry-run` to list exactly which files would ship, and `npm publish --dry-run` to see the registry call without making it. It installs Chromium for Playwright and runs `npm test` so the workflow's test step is known to pass on the same commands. It also runs `node -e "import('@lit/lit-starter-ts')"` from a scratch directory against the packed tarball to confirm the `exports` map resolves. The agent never creates a tag and never publishes; the pull request describes the `git tag v2.0.4 && git push --tags` step a maintainer runs after merging.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add an npm release workflow to this Lit component. Read package.json, tsconfig.json, .gitignore, .eslintignore, rollup.config.js, web-test-runner.config.js, src/my-element.ts, src/test/my-element_test.ts, CHANGELOG.md and README.md first. Make the package publishable: drop private, add files, exports with types, sideEffects, publishConfig access public and a prepack script that builds and runs the custom elements analyzer. Write .github/workflows/release.yml on push of v* tags with id-token write, setup-node 22 against registry.npmjs.org, npm ci, Playwright Chromium install, lint, test, build, a check that the tag matches package.json version, and npm publish --provenance --access public using trusted publishing, with a comment showing the NPM_TOKEN alternative. Verify with npm pack --dry-run, npm publish --dry-run, the test suite and an import of the packed tarball. Do not create a tag or publish. Open a pull request that lists the tarball contents and the maintainer's tagging step.",
  "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 adds `.github/workflows/release.yml` and changes `package.json`; `README.md` gains a short Releasing section. Its description pastes the `npm pack --dry-run` file list, the `npm publish --dry-run` output, the `wtr` test summary for dev and prod mode, and the import check against the packed tarball, so a reviewer sees what would ship before anything does.

Because the workflow runs only on a `v*` tag, merging the pull request publishes nothing. The first real run happens when a maintainer tags a release, and that run's log on GitHub shows the version guard, the tests and the provenance attestation. The run's record on Rush keeps every sandbox command, including the dry runs, for anyone who wants to compare.

Before merging, a reviewer confirms the package name they own on npmjs.com, sets up trusted publishing for this repository and workflow or adds `NPM_TOKEN` as a secret, and decides whether `CHANGELOG.md` should be updated by hand or by a changesets action in a later pull request.

## Run it on every Lit component repository without a release workflow

A team that maintains several components starts one run per repository from its own server: a `POST /o/{org}/sessions` each, with the repository in `resources` and 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 reads its own `package.json`, so a package that already publishes gets a report instead of a workflow, and a monorepo gets the workflow scoped to the package directory it finds.

To keep the tarball honest, an automation in the Project with a `github` trigger on `pull_request.opened` and the prompt "if this pull request adds a source file or a build output, check it is covered by the files list in package.json and the exports map, and say so in a comment" reviews each change. The trigger adds the pull request after the prompt and fires only for work by owners, members and collaborators.

## Why run it on Rush?

A release workflow is the kind of file people copy from another repository and discover is wrong on the first tag: the tarball ships the docs site because `files` was never set, the test step fails because Playwright has no browser on the runner, or the package publishes under a version that does not match the tag. The agent reads the real `package.json` and `.gitignore`, packs the tarball in its sandbox and runs the tests on the same commands the workflow will use, so the first tag has already been rehearsed.

Every command stays with the run, from `npm pack --dry-run` to the import check, and the pull request quotes them. Nothing is tagged and nothing is published by the agent, so the maintainer keeps the one step that matters.

## Frequently asked questions

### Why trusted publishing instead of an NPM_TOKEN secret?

Trusted publishing links the npm package to this repository and workflow through GitHub's OIDC token, which is why the workflow asks for `id-token: write`; there is no long-lived token to leak or rotate, and `--provenance` attaches a verifiable build record. It needs a one-time setup on npmjs.com for the package. For a registry without it, the pull request shows the `NODE_AUTH_TOKEN` line to add under `npm publish`.

### What ends up in the tarball?

Only what the new `files` list names: the emitted `my-element.js`, its `.d.ts`, both maps, the TypeScript source and `custom-elements.json`. The `docs/` site, `docs-src/`, `dev/`, the rollup config and the tests stay out. The `npm pack --dry-run` output in the pull request is the exact list.

### Will the tests run on the GitHub runner?

Yes, because the workflow runs `npx playwright install --with-deps chromium` before `npm test`. `web-test-runner.config.js` uses the Playwright launcher, which needs a browser the runner does not have by default. The agent runs the same install in its sandbox to confirm the step.

### Does merging this publish anything?

No. The workflow triggers only on a pushed tag matching `v*`, and the agent neither tags nor publishes. The pull request ends with the maintainer's step: bump `version` in `package.json`, commit, `git tag v2.0.4` and `git push --tags`. The version guard fails the job if the tag and the file disagree.

## More Lit jobs

- [Add Server-Side Rendering to a Lit Component](https://getrush.ai/run/add-ssr/lit/)
- [Set Up Storybook for Lit Web Components](https://getrush.ai/run/add-storybook/lit/)
- [Migrate a Lit Component Library to ESLint Flat Config](https://getrush.ai/run/migrate-eslint-flat-config/lit/)

## The same job on other stacks

- [Add a Release Workflow for a Maven Library](https://getrush.ai/run/add-release-workflow/maven/)
- [Add a GitHub Release Workflow to an Obsidian Plugin](https://getrush.ai/run/add-release-workflow/obsidian-plugin/)
- [Add a Release Workflow for a Textual App](https://getrush.ai/run/add-release-workflow/textual/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
