Skip to main content

Getting started

Installation​

Projects generated from the basic or shop template ship with Storybook preconfigured — nothing to install.

For an existing project, run archibald add and select the storybook function. It

  • installs @archibald/storybook plus the Storybook 10 packages as dev dependencies (storybook, @storybook/react, @storybook/react-webpack5, the docs, a11y, and onboarding addons, @chromatic-com/storybook, @storybook/addon-webpack5-compiler-swc, and eslint-plugin-storybook),
  • copies the .storybook/ configuration template into the project (unless one already exists),
  • adds .storybook to the include array of your tsconfig.json, and
  • adds a "storybook": "archibald storybook" script to your package.json.

Since Storybook 9/10 and the builder are peer dependencies of @archibald/storybook, they live in your project's own package.json — see the v9 migration notes if you are upgrading from an older setup.

The .storybook/ folder​

The Storybook configuration lives in .storybook/ at the project root (configurable via cli/storybook/config in archibald.json). The shop template contains:

.storybook/
├── main.ts             # Storybook config, built with defineConfig()
├── preview.tsx         # global decorators: StorybookProvider, global styles
├── manager.ts          # Storybook UI (manager) configuration
├── manager-head.html   # extra tags for the manager <head>
├── theme.ts            # Storybook UI branding
├── context/i18n.ts     # helper that seeds translation data into the context
├── i18n/en.ts          # translation messages used by the stories
└── tsconfig.json       # TypeScript settings for the config files

main.ts​

The template's main.ts is a single call to defineConfig() from @archibald/storybook/config:

.storybook/main.ts
import { defineConfig } from '@archibald/storybook/config';

export default defineConfig();

defineConfig() registers the framework (@storybook/react-webpack5), the Archibald preset, the shadowing-aware story loader, and a default addon set (@storybook/addon-docs, @storybook/addon-a11y, @storybook/addon-onboarding, @chromatic-com/storybook). Anything you pass to defineConfig({...}) is deep-merged on top — see How it works for the merge rules.

preview.tsx​

preview.tsx wraps every story in the StorybookProvider and imports the global stylesheet through the base path, so the shadowing-aware SCSS pipeline applies:

.storybook/preview.tsx (excerpt)
import { StorybookProvider } from '@archibald/storybook';
import type { Preview } from '@storybook/react-webpack5';

import { createI18nContext } from './context/i18n';

import 'shop/resources/scss/base/global.scss';

const { dataClient, appClient } = createI18nContext();

const preview: Preview = {
    decorators: [
        (Story) => (
            <StorybookProvider context={{ dataClient, appClient }}>
                <div className="theme" style={{ minHeight: 'auto' }}>
                    {Story()}
                </div>
            </StorybookProvider>
        )
    ],
    tags: ['autodocs']
    // parameters, initialGlobals, ...
};

export default preview;

manager.ts and theme.ts only brand the Storybook UI (storybook/manager-api + storybook/theming/create) and are plain Storybook configuration.

Running Storybook​

archibald storybook

(aliases: archibald sb, archibald story)

Like archibald serve, the command interactively prompts for:

  • environment — one of project/environments from archibald.json,
  • tenant — one of project/tenants,
  • platform — one of project/platforms,
  • mode — development or production.

Each prompt can be skipped by passing the matching flag (-e, -t, -p, -m), and -q, --quiet runs entirely non-interactively with defaults. See the CLI reference for all options.

In development mode Storybook starts a dev server on the port from cli/storybook/port (default 3400); whether the browser opens automatically is controlled by cli/storybook/open (default true, overridable with -o). The tenant and platform you select determine which shadowed files and stories are compiled — switching tenants requires a restart.

Production build​

archibald storybook -m production

builds a static Storybook into <dist>/<storybook> — by default dist/stories (project/output/paths/dist + project/output/paths/storybook).

If cli/storybook/vercel/active is true in archibald.json, the command additionally offers a --vercel (-vrcl) flag that transforms the static build into a Vercel Build Output under .vercel/output:

archibald storybook -m production --vercel

See Deploying Storybook to Vercel for the full setup.