All jobs

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

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

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

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

The same job on other stacks

More jobs like this: Hand off a long task

Keep reading