Bring Fiddle to your app

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, so Storybook reads the same files.

Write one

Any *.stories.tsx under src/:

src/onboarding.stories.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.

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 and it renders live. Put up to four links on consecutive lines to compare them side by side.