# Stories

> Review every state of a component or flow, drawn by your app's own code, without a test account or a deploy.

A story is one state: the happy path, an error, an empty list, step three of onboarding. Stories are [CSF](https://storybook.js.org/docs/api/csf), so Storybook reads the same files.

## Write one

Any `*.stories.tsx` under `src/`:

```tsx
import type { Meta, StoryObj } from "@basswood/fiddle/stories"
import { http, HttpResponse } from "msw"
import { OnboardingPage } from "./onboarding"

const meta = {
  title: "Onboarding",
  component: OnboardingPage,
  parameters: { msw: { handlers: [http.get("/api/me", () => HttpResponse.json(me))] } },
} satisfies Meta<typeof OnboardingPage>
export default meta

type Story = StoryObj<typeof meta>

export const Welcome: Story = {}
export const InvalidToken: Story = {
  args: { step: "connect" },
  parameters: {
    msw: { handlers: [http.post("/api/claim", () => HttpResponse.json({ error: "Already used" }, { status: 400 }))] },
  },
}
```

Fiddle reads `args` and `argTypes` (as controls), `decorators`, `loaders`, `beforeEach`, `render`, `play` and `parameters.msw.handlers`. Shared setup goes in `.fiddle/preview.tsx`.

## Run them

```bash
npx fiddle stories dev      # http://localhost:6006/__fiddle/
npx fiddle stories build    # a static site in fiddle-stories/
npx fiddle stories publish  # to Fiddle, as a build of your branch
```

Stories run on Vite with your app's own config. Apps not on Vite get a config made for them; install `vite` and `@vitejs/plugin-react`.

Each story is isolated: it loads fresh, its storage starts empty, and any request no handler answers is stopped instead of reaching your backend.

## Publish

`fiddle stories publish` uploads the build and hosts it with the toolbar on every page:

- `https://<branch>--<app>.fiddle.page/__fiddle/` is the branch's newest build. Share this one.
- `https://<commit>--<app>.fiddle.page/__fiddle/` is that exact build.

Sign in once per machine with `npx fiddle login`. Agents use `create_build_upload_url`; CI uses an API key in `FIDDLE_API_KEY`. See [CLI](https://docs.fiddle.fyi/cli.md).

## Review them

On the app's page, **Stories** shows one story at a time. Pick a build, search, change controls, and switch between phone, tablet and desktop sizes. Press **Comment** and click anything.

## In a document

Paste a story's link on its own line in a [document](https://docs.fiddle.fyi/documents.md) and it renders live. Put up to four links on consecutive lines to compare them side by side.
