# Set Up Storybook for Lit Web Components

Yes. An agent installs Storybook's web-components-vite framework in your Lit project, writes stories, keeps tsc and the tests clean, builds it and opens a PR.

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

## What the agent does

The agent reads the project's build and test setup before adding a tool that has opinions about both. In a project like lit/lit-element-starter-ts, `package.json` depends on `lit` 3.2 and builds with plain `tsc`: `tsconfig.json` sets `rootDir` to `src`, `outDir` to the repository root, `target` `es2021`, `experimentalDecorators` and a `ts-lit-plugin`, and includes `src/**/*.ts`, so `npm run build` emits `my-element.js` next to `package.json`, which `.gitignore` already lists. Tests run through `@web/test-runner` with Playwright launchers for Chromium, Firefox and WebKit against the compiled `test/**/*_test.js`, the dev server is `@web/dev-server`, bundling for the docs site is Rollup with Terser, lint is ESLint 8 plus `lit-analyzer`, and a `docs` script runs Eleventy over `docs-src/` with the Custom Elements Manifest produced by `cem analyze`. The one component, `src/my-element.ts`, is a `LitElement` with a `name` string property, a `count` number property, a button that increments `count` and fires a `count-changed` event, a default slot and a `button` CSS part. There is no Storybook, no Vite and no `.github/workflows/` directory.

Then it installs the framework that matches a Lit project. `@storybook/web-components-vite` at its current 10.x release, which accepts Vite 5 through 8, goes in through `npm create storybook@latest` or by hand when the initializer asks questions a sandbox cannot answer: `storybook`, the framework package and `vite` as dev dependencies, `storybook` and `build-storybook` scripts, `.storybook/main.ts` with `framework: '@storybook/web-components-vite'` and a `stories` glob of `../src/**/*.stories.ts`, and `.storybook/preview.ts`. Because `tsconfig.json` compiles everything under `src/` to the repository root, a story file there would make `npm run build` emit `my-element.stories.js` beside the package entry, so the agent adds `src/**/*.stories.ts` to the `exclude` list and `storybook-static/` to `.gitignore`, and confirms `npm run build` and `npm run clean` behave as before.

The story follows the Storybook template for web components rather than a React habit. `src/my-element.stories.ts` imports `html` from `lit`, `Meta` and `StoryObj` types, and `fn` from `storybook/test`, declares `component: 'my-element'` with a `title`, `tags: ['autodocs']`, `args` of `name: 'World'` and `count: 0`, `argTypes` giving `count` a number control, and a `render` that returns a lit `html` template binding `.name`, `.count` and `@count-changed=${args.onCountChanged}` around some slot content, so the event shows in the Actions panel. Three stories, `Default`, `Named` and `Clicked`, cover the properties and the slot, and the autodocs page picks up the JSDoc that `cem analyze` already reads, including the `@fires`, `@slot` and `@csspart` tags on the class.

It proves nothing else moved. `npm run build-storybook` writes `storybook-static/`, and the agent opens the built `index.json` to confirm the three stories and the docs entry are listed. `npm run lint` runs ESLint and `lit-analyzer` over the story file too; `npm run build` emits no story output; and `npm test` runs the existing five tests in the three browsers it can install in the sandbox. The `docs` script and Eleventy site are left alone, and `README.md` gains a short Storybook section after the Dev Server one.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Set up Storybook for this Lit TypeScript project. Read package.json, tsconfig.json, rollup.config.js, web-test-runner.config.js, .eslintrc.json, .gitignore, src/my-element.ts and src/test/my-element_test.ts first. Add storybook, @storybook/web-components-vite and vite as dev dependencies with storybook and build-storybook scripts, write .storybook/main.ts with the web-components-vite framework and a stories glob under src, and .storybook/preview.ts. Exclude *.stories.ts from tsconfig.json so npm run build emits nothing for them, and add storybook-static to .gitignore. Write src/my-element.stories.ts with html from lit, component set to my-element, autodocs, args and argTypes for name and count, an action for the count-changed event, and Default, Named and Clicked stories. Run npm run build-storybook and check the stories in the built index, then npm run lint, npm run build and npm test, and fix anything the new files broke. Add a Storybook section to README.md and open a pull request that lists the stories and the tsconfig change.",
  "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 `.storybook/main.ts`, `.storybook/preview.ts` and `src/my-element.stories.ts`, adds three dev dependencies and two scripts to `package.json` with the matching `package-lock.json`, excludes story files in `tsconfig.json`, ignores `storybook-static/`, and adds a README section. The description lists the three stories and the autodocs entry as the built `index.json` names them, states the Storybook and Vite versions resolved, and explains the `tsconfig.json` exclusion so nobody removes it later.

The run's record keeps the install output, the `build-storybook` log, the `index.json` check, and the `lint`, `build` and `test` runs, so a reviewer can see the existing checks pass with the new files in the tree.

Before merging, a reviewer runs `npm run storybook`, clicks the button in the `Default` story to see `count-changed` in the Actions panel, and decides whether to add a workflow that builds Storybook on pull requests, since the repository has none yet.

## Run it on every pull request adding an element

Once Storybook is in place, keep it complete with an automation on the Project: this prompt rewritten as "write a story for any new custom element this pull request adds, following src/my-element.stories.ts", with a `github` trigger on `pull_request.opened` and `pull_request.synchronize`. The trigger puts the pull request after the prompt; only pushes by an owner, member or collaborator fire it, never a fork's. The run reads the diff, writes the missing story, and pushes it to the pull request's branch.

From your own server, the setup itself goes to `POST /o/{org}/sessions` once per component library, each with its 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 rather than a second pull request.

## Why run it on Rush?

Adding Storybook to a project that compiles `src/` to its root with `tsc` is the kind of change that looks done when the dev server opens and breaks `npm run build` or `npm publish` a week later. The agent runs the project's own `build`, `lint` and `test` scripts after the install in its sandbox, with the three Playwright browsers the test runner expects, and fixes the `tsconfig.json` interaction before the pull request exists.

The built `index.json`, the lint output and the test run stay with the record, so the pull request can state exactly which stories exist and that the five existing tests still pass, rather than asking a reviewer to install and find out.

## Frequently asked questions

### Why does Storybook need Vite when the project uses Rollup and tsc?

Storybook's web-components framework runs on Vite as its builder, which is why `vite` is installed as a dev dependency. The project's own `build`, `docs` and `test` scripts keep using `tsc`, Rollup and `@web/test-runner`; Vite only serves and bundles the stories.

### Will stories end up in the published package?

No. `tsconfig.json` excludes `src/**/*.stories.ts`, so `tsc` emits nothing for them, and `storybook-static/` is ignored by git. The pull request names the exclusion so it is not removed by accident.

### Do the decorators in my-element.ts work in Storybook?

Yes. Vite reads `experimentalDecorators` from `tsconfig.json` and the component's `@customElement` and `@property` decorators compile as they do under `tsc`. The agent confirms this by building Storybook rather than assuming it.

### Does it generate docs from the JSDoc?

The `autodocs` tag gives each story file a documentation page, and the `@fires`, `@slot` and `@csspart` tags on the class are the same ones `cem analyze` reads for the existing Eleventy docs. Wiring the Custom Elements Manifest into Storybook for richer controls is a follow-up the pull request mentions.

## More Lit jobs

- [Migrate a Lit Component Library to ESLint Flat Config](https://getrush.ai/run/migrate-eslint-flat-config/lit/)
- [Upgrade npm Dependencies Weekly for a Lit Component Library](https://getrush.ai/run/upgrade-npm-dependencies/lit/)
- [Add Accessibility Tests to a Lit Component](https://getrush.ai/run/add-accessibility-tests/lit/)

## The same job on other stacks

- [Add Storybook to a SolidJS App](https://getrush.ai/run/add-storybook/solidjs/)
- [Add Storybook to an Expo App](https://getrush.ai/run/add-storybook/expo/)

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

- [Add Streaming Responses to a Hono API](https://getrush.ai/run/add-streaming-responses/hono/)

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