# Add Changesets to a TypeScript Library

Yes. An agent installs Changesets, writes its config, a release workflow that opens a version PR and publishes to npm, and a status check, and opens a PR.

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

## What the agent does

The agent clones the repository into its own cloud sandbox and reads how the library is built, tested and released today. In a library like sindresorhus/ky, `package.json` is at version `2.2.0`, `"type": "module"`, with `exports` pointing at `distribution/index.js` and `files` limited to `distribution`. The `test` script chains `xo`, `npm run build`, `tsc --project tsconfig.test.json` and `ava`; `build` runs `del-cli distribution && tsc --project tsconfig.dist.json`; `prepare` runs the build; and `release` is `np`, a tool a maintainer runs from a laptop. `.npmrc` sets `package-lock=false`, `engines` asks for Node 22 or newer, and the one workflow, `.github/workflows/main.yml`, runs `npx ava 'test/**' '!test/browser.ts'` on three Node versions plus a browser job that installs Playwright and runs `npm test -- test/browser.ts`. There is no `CHANGELOG.md`, no `.changeset/` directory and no workflow that publishes. The agent also reads `AGENTS.md`, which sets conventions for the source, so nothing it adds contradicts them.

It installs `@changesets/cli` as a dev dependency with `npm install`, which writes no lockfile because of the `.npmrc`, runs `npx changeset init`, and edits the generated `.changeset/config.json`: `baseBranch` set to `main`, `access` to `public` since the package is public on npm, and the default `changelog` generator kept so `CHANGELOG.md` is written from the changeset summaries at version time. In `package.json` the `release` script changes from `np` to `npm run build && changeset publish`, a `version` script runs `changeset version`, and `prepare` stays as it is. Because `files` only ships `distribution/` and the build cleans that directory first, the publish command builds before it publishes rather than trusting a stale build.

A new `.github/workflows/release.yml` runs on push to `main`: checkout and setup-node pinned to the same majors `main.yml` uses, `npm install`, then `changesets/action` with `version: npm run version` and `publish: npm run release`, a `GITHUB_TOKEN` with `contents: write` and `pull-requests: write` permissions, and an `NPM_TOKEN` secret the maintainer adds. With pending changesets the action opens or updates a `Version Packages` pull request that bumps `package.json` and `CHANGELOG.md`; merging that pull request runs the publish. The agent also adds one step to the static checks job in `main.yml`, `npx changeset status --since=origin/main`, so a pull request that changes `source/` without a changeset fails that job and says why, and writes a `.changeset/README.md` paragraph on `npx changeset` for contributors.

In the sandbox the agent runs `npm install`, `npx changeset status`, the `xo` lint and build steps and `npx ava 'test/**' '!test/browser.ts'`, exactly what the CI job runs without a browser, to show the scripts still work. It then tries `npx changeset version` on a throwaway branch with a sample patch changeset to show the `CHANGELOG.md` and version bump it would produce, pastes the diff into the pull request, and resets the branch so the pull request itself carries no version bump.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add Changesets to this TypeScript library. Read package.json, .npmrc, the tsconfig files and .github/workflows/main.yml first. Install @changesets/cli as a dev dependency, run changeset init, set baseBranch to main and access to public in .changeset/config.json, and keep the default changelog generator. Replace the np release script with a build followed by changeset publish, add a version script, and leave prepare alone. Add a release workflow on push to main that uses changesets/action to open the Version Packages pull request and publish with an NPM_TOKEN secret, pinned to the same action majors main.yml uses. Add a changeset status step to the static checks job so source changes without a changeset fail, and a short contributor note. Run install, lint, build and the non-browser ava tests, show what changeset version would produce on a scratch branch without committing it, and open a pull request.",
  "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 that adds `.changeset/config.json`, `.changeset/README.md` and `.github/workflows/release.yml`, and changes `package.json` and `.github/workflows/main.yml`. The description walks through the new release path in four steps, contributor adds a changeset, pull request merges, `Version Packages` pull request appears, merging it publishes, pastes the lint, build and test output, and shows the `CHANGELOG.md` the scratch `changeset version` produced.

The run's record keeps every command, including the `changeset status` output and the scratch version run, so a reviewer can see the generated changelog format before any real version is cut.

Before merging, a reviewer adds the `NPM_TOKEN` secret, or swaps the publish step for npm trusted publishing if the package already uses it, decides whether the first changeset should be a `patch` or a `minor`, and confirms the branch protection on `main` allows the action's bot to open the version pull request.

## Run it on every new package in the organization

In the console, an automation in the Project that has the repository, with a `github` trigger on `pull_request.opened` and `branch_patterns` for your default branch, starts one run per pull request with the pull request as its context; the prompt tells the run to add the Changesets setup when the repository has no `.changeset/` directory yet and to do nothing otherwise. An organization that keeps one Project per library can start the same automation in each.

From your own server, the same work is one `POST /o/{org}/sessions` per repository with this body and the repository in `resources`, with a `request_id` that is a UUID v5 of the repository name so a retried call returns the run already started. A webhook URL on the API key reports `run.completed` with the `session_url` to read the pull request link from.

## Why run it on Rush?

Moving a release process off a maintainer's laptop touches the scripts, the lockfile policy, the CI and the publish credentials at once, and a mistake publishes a broken version or nothing at all. The agent reads how the package is built and shipped, keeps `prepare` and `files` as they are, builds before it publishes, and runs the same lint, build and test commands CI runs before the pull request exists.

The sandbox is its own computer with the Node version the package asks for, every command and its output stays in the run's record, and a scratch `changeset version` shows the reviewer the changelog format without a real bump. Several libraries can get the same setup at once, each in its own sandbox with its own pull request.

## Frequently asked questions

### Does this change how contributors open pull requests?

Slightly. A pull request that changes `source/` now includes a file under `.changeset/` created with `npx changeset`, which names the bump type and a one-line summary. The new status step in CI fails with a clear message when it is missing, and the contributor note explains the command.

### Will the first release still work with np?

The `release` script no longer calls `np`, so a maintainer who prefers it can still run `npx np` by hand, but the workflow publishes from CI once the `Version Packages` pull request merges. Running both would publish twice, so the pull request recommends one path.

### Why no lockfile in the pull request?

Because `.npmrc` sets `package-lock=false`, so `npm install` of the new dev dependency changes only `package.json`. The agent keeps that policy; the release workflow runs `npm install` the way `main.yml` already does.

### Can the publish use npm trusted publishing instead of a token?

Yes. The workflow's publish step needs `id-token: write` and the package needs a trusted publisher configured on npm; the pull request shows the two-line change. The agent defaults to an `NPM_TOKEN` secret because that works before anything is configured on npm.

## More TypeScript library jobs

- [Add CodeQL Scanning to a TypeScript Library](https://getrush.ai/run/add-codeql-scanning/typescript-library/)
- [Add Test Coverage Reporting to CI for a TypeScript Library](https://getrush.ai/run/add-coverage-to-ci/typescript-library/)
- [Run a TypeScript Library's Tests on Bun and Deno in CI](https://getrush.ai/run/add-cross-runtime-tests/typescript-library/)

## More jobs like this: Hand off a long task

- [Add Checkov Scanning to a Terraform Module's CI](https://getrush.ai/run/add-checkov-to-ci/terraform/)
- [Add Checkstyle to a Maven Build](https://getrush.ai/run/add-checkstyle/maven/)
- [Add a clang-format Check to CI for a CMake Project](https://getrush.ai/run/add-clang-format-check/cmake/)

## 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/)
