Quick start

The fastest way to set up stageboard is to let your coding agent do it. The manual path below does the same steps by hand.

Let your agent set it upCopy Anchor Link

Paste this prompt into Claude Code, Codex, atmOS or any agent that reads .claude/skills or .agents/skills:

Set up stageboard in this repo. Run `npm i -D stageboard` (use this repo's package manager), then
`npx stageboard skill` to install the stageboard skill, and follow it: write the config and a preview
with mock providers, add stories for the main components, put every page in Screens with realistic
mock data, and check each one with `npx stageboard shot`. Finish by listing the stories that look weak.

The skill tells the agent how to write the config, mock providers, stories and page stories, and to check each one with a screenshot.

Set it up by handCopy Anchor Link

1. InstallCopy Anchor Link

npm i -D stageboard

stageboard needs react and react-dom 18 or later. It runs on Vite 6 or later.

2. Create the configCopy Anchor Link

npx stageboard init

This writes stageboard.config.ts in the current directory:

import { defineConfig } from "stageboard"

export default defineConfig({
  stories: ["src/**/*.stories.tsx"],
  preview: "./stageboard.preview.tsx",
  agent: { provider: "claude" },
})

Create the preview file it points to. It imports your global CSS and exports decorators that wrap every story, for example in your providers:

import "./src/styles.css"
import type { Decorator } from "stageboard"

export const decorators: Decorator[] = [(Story) => <div className="font-sans antialiased"><Story /></div>]

Add .stageboard/ (local state and caches) to .gitignore. See Configuration for every option.

3. Write a first storyCopy Anchor Link

import type { Meta, Story } from "stageboard"
import { Button } from "./button"

export default { title: "Primitives/Button", component: Button, args: { children: "Save" } } satisfies Meta<typeof Button>

export const Primary: Story<typeof Button> = {}
export const Disabled: Story<typeof Button> = { args: { disabled: true } }

Story ids are kebab(title)--kebab(export), so these are primitives-button--primary and primitives-button--disabled. npx stageboard list prints them. See Stories for the full format.

4. Start the boardCopy Anchor Link

npx stageboard dev

Open http://localhost:6060/__stageboard/. The port defaults to 6060 (or STAGEBOARD_PORT), and stageboard moves to the next free port if it is taken; the terminal prints the actual URL. Use --port and --host to change them.

To check a story without opening the board, take a screenshot:

npx stageboard shot primitives-button--primary --width 1440 --out /tmp/button.png

5. Install the agent skillCopy Anchor Link

npx stageboard skill

This copies the stageboard skill into .claude/skills/stageboard and .agents/skills/stageboard. Pass --claude or --codex to install only one of them. Run it again after upgrading stageboard.

Next stepsCopy Anchor Link

• Stories and Screens: cover your components and every page.
• Flows: string screens into user journeys.
• Annotate: point at what is wrong and send it to an agent.
• Agents: pick Claude Code, Codex, atmOS or your own CLI.
• Next.js: use the Next.js preset.
• CLI reference: every command and flag.