What the agent does
Storybook is several packages that have to agree, so the agent starts by listing them. In a project like chromaui/intro-storybook-react-template, package.json has storybook, @storybook/addon-docs, @storybook/addon-vitest, @storybook/react-vite and eslint-plugin-storybook all at ^10.1.11, and yarn.lock resolves each to 10.1.11. @chromatic-com/storybook sits beside them on its own version line. The lock also records what the addons expect from their neighbours: @storybook/addon-vitest declares a peer range on storybook and on vitest and @vitest/browser-playwright, which here are on 4. An upgrade that moves storybook alone leaves the rest behind, and one that crosses a major may need Vitest or Vite to move too.
It then reads what the code imports from Storybook, since those are the lines a release can break. Stories import types from @storybook/react-vite and fn, expect, userEvent and within from storybook/test. src/stories/Configure.mdx imports Meta from @storybook/addon-docs/blocks. vite.config.ts imports storybookTest from @storybook/addon-vitest/vitest-plugin, and .storybook/vitest.setup.ts calls setProjectAnnotations. .storybook/main.ts names the framework, the three addons and staticDirs. With that list and the migration guide for each major between the installed version and the target, the agent knows which entries of the guide apply before it runs anything.
Before upgrading it records a baseline with the repository's own tools. yarn install --immutable uses the Yarn release committed under .yarn/releases and named in packageManager. Then yarn build-storybook, yarn vitest run --project=storybook after installing Chromium with yarn playwright install --with-deps chromium, yarn tsc -b and yarn build. There is no test or lint script here, so those four commands are the definition of working.
The upgrade itself is Storybook's own command, yarn dlx storybook@latest upgrade, run so that it applies its automigrations without prompting. The agent reads what each automigration changed and keeps the diff only where it is correct for this project. It runs yarn dlx storybook@latest doctor, which reports mismatched or duplicated Storybook packages, and fixes what it reports. When the new addon peer ranges require it, it moves vitest, @vitest/browser-playwright, @vitest/coverage-v8 and playwright together and no further than the range asks. It repeats the four baseline commands, fixes each new failure with the change the migration guide documents, and leaves the resolutions entry and the Yarn version as they are unless the upgrade cannot install without touching them.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Upgrade Storybook in this repository to the latest stable release. Read package.json, yarn.lock, .yarnrc.yml, .storybook/main.ts, .storybook/preview.ts, .storybook/vitest.setup.ts, vite.config.ts, the tsconfig files and every story and MDX file first. List every Storybook package with its declared and resolved version, the peer ranges the addons declare in yarn.lock, and every import from a Storybook package in the code. Install with yarn install --immutable, install Chromium with yarn playwright install --with-deps chromium, and record a baseline: yarn build-storybook, the Vitest storybook project, yarn tsc -b and yarn build. Read the migration guide for each major between the installed version and the latest and write a checklist of the entries that apply to this project's framework, addons and imports. Run yarn dlx storybook@latest upgrade without prompts, review what each automigration changed and revert any change that is wrong for this project, saying why. Run yarn dlx storybook@latest doctor and resolve what it reports. Keep every Storybook package on the same version. Move vitest, its browser and coverage packages, playwright or vite only if a peer range of the new Storybook requires it, and only as far as required. Do not change the Yarn version or the resolutions field unless the install fails without it. Rerun the four baseline commands and fix each new failure with the change the migration guide documents; do not delete or skip a story. Open a pull request with the version table before and after, the checklist with each entry marked applied or not applicable and the file it touched, the list of automigrations with what each changed, and the output of the four commands before and after. List anything broken before the upgrade separately and do not fix it here.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- 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.
- 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.
- 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
A pull request that changes package.json, yarn.lock and whichever files under .storybook, src and the Vite config the new release required. The description opens with a table of every Storybook package, its version before and its version after, so a reviewer sees at a glance that they still match, and a second table for any neighbour that had to move with them.
Next is the migration checklist, each entry marked applied with the file it touched or not applicable with the search that found no use of the changed API, and the automigrations the upgrade command ran with a one-line account of each. The four commands appear twice, with their output on the base commit and on the branch. A failure present in both is listed under problems that predate the upgrade and is not fixed here.
A reviewer opens the built Storybook or runs yarn storybook on the branch and clicks through the stories, because a build that succeeds can still render a docs page differently. They read any automigration the agent reverted and its reason. If the team publishes to a visual review service, that service's check on the pull request is the place to see rendering changes; the agent's sandbox run does not replace it.
Run it on every Storybook release
An automation in the Project that holds the repository, with this prompt and a schedule trigger, checks on a rhythm you choose: a cron for one morning a month in your timezone suits minors, and a major is better started by hand when the team has time to review it. When the installed version is already the latest, the run ends without a pull request.
A design system team with many consuming repositories runs it from a script instead: list the repositories with GET /o/{org}/github, and send this body to POST /o/{org}/sessions once for each, with a request_id that is a UUID v5 of the repository's full name and the target version so a second pass starts nothing twice. Each run opens its own pull request in its own repository.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
A Storybook upgrade is rarely hard and often slow: install, build, find the addon that lags a version, read the guide, adjust a config, build again, run the stories in a browser, and repeat. Each round takes minutes of waiting on a bundler and a headless browser. In a sandbox those rounds run unattended, and when several repositories share a component library they are upgraded in parallel, each in a separate sandbox with a fresh install.
What comes back is checkable. The baseline and the final outputs are both in the description, and the commands behind them, the failed attempts included, are in the run's transcript at GET /o/{org}/sessions/{id}/messages. A reviewer does not have to trust that the stories were run; they can read the run.
Frequently asked questions
Does it handle a major version upgrade, or only minors?
Both. For a major it reads the migration guide for each major it crosses and applies the entries that match this project's framework, addons and imports. If the project is several majors behind, the pull request groups the changes by major so they can be reviewed in order.
What happens to addons that have no release for the new version?
The agent checks each addon's published peer range against the target. An addon with no compatible release is named at the top of the pull request with its latest version and range, and the agent stops at the newest Storybook that every installed addon supports unless the prompt says to drop the addon.
Will it switch our package manager or lockfile?
No. It installs with the Yarn release the repository pins in packageManager and .yarnrc.yml and updates yarn.lock with that same Yarn. A project on npm or pnpm gets the same treatment with its own lockfile.
We have no tests for our stories. Is the upgrade still verified?
Partly. The Storybook build and the type check still run, and they catch removed imports and config keys. If the Vitest addon is configured, every story is at least rendered in a browser. The description states which of these checks existed, so a reviewer knows how much the green output covers.
More Storybook jobs
More jobs like this: Upgrade dependencies weekly
- Upgrade Strapi to the Latest Version (Strapi)
- Upgrade Symfony and Its Dependencies (Symfony)
- Upgrade Terraform Providers in a Terraform Module (Terraform)