All jobs

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 RushOpens 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 with this body:

{
  "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.

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

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

The same job on other stacks

Keep reading