@presetter/preset-storybook
A standalone Presetter preset that wires up Storybook, accessibility checks, and Vitest browser testing — drop it on top of any framework preset.
The storybook preset generates a ready-to-run .storybook setup, Storybook scripts, ESLint rules for stories, and a Vitest browser project so your stories double as component tests.
@presetter/preset-storybook is independent from @presetter/preset-web, so you can add Storybook to any project (React, Next.js, etc.) without pulling in browser/Tailwind settings unless you need them.
Purpose
@presetter/preset-storybook is designed to extend a framework preset rather than replace it. When composed, it:
- Generates Storybook config — emits
.storybook/main.tswith story globs derived from yoursourcedirectory and the@storybook/addon-a11yand@storybook/addon-vitestaddons. - Adds Storybook scripts —
storybook,build:storybook, and apretest:unit:playwrightstep that installs Playwright's Chromium on demand. - Enables accessibility linting — overrides
eslint.config.tswitheslint-plugin-storybook's recommended flat config. - Runs stories as tests — overrides
vitest.config.tsto add a headless Chromium browser project powered by@storybook/addon-vitestand@vitest/browser-playwright.
Features
.storybook/main.ts— story globs resolved relative to the Storybook config dir, plus the a11y and Vitest addons.- Storybook scripts —
storybook(storybook dev -p 6006) andbuild:storybook(storybook build). - On-demand Playwright — a
pretest:unit:playwrightstep joins the unit steps to runplaywright install --with-deps chromiumunlessPLAYWRIGHT_READY=1.runfires it through thepretesthook oftest(and oftest:coverageandtest:watch, which runtest), thepretest:unithook oftest:unit, and thepretest:stohook oftest:sto. - ESLint story rules —
eslint-plugin-storybookflat/recommendedplus a**/*.stories.[jt]sxoverride that disablescompat/compat. - Vitest browser project — headless Chromium runner with
globals: true, sensible timeouts, and noise-filtering for benign Reactact()warnings.
Installation
Quick Start
# install the preset alongside a framework preset (Next.js shown)
npx presetter use @presetter/preset-next @presetter/preset-storybook
Declared Setup
use installs Storybook, the a11y and Vitest addons, the Vitest Playwright browser provider, Playwright, the Storybook ESLint plugin, and Vitest as development dependencies. It also adds storybook, build:storybook, and test:sto delegates. Existing declarations and scripts are preserved.
Install the Storybook framework package for your application separately; for the Next.js example below:
npm install --save-dev @storybook/nextjs-vite
For manual adoption, install the packages declared in the preset's setup.devDependencies and add its script delegates before bootstrapping.
Usage
The storybook preset is meant to be combined with a framework preset:
import next from '@presetter/preset-next';
import storybook from '@presetter/preset-storybook';
import { preset } from 'presetter';
export default preset('app', {
extends: [next, storybook],
});
Selecting the Storybook framework
By default .storybook/main.ts does not pin a framework. For a Next.js project, override the asset to use @storybook/nextjs-vite — the canonical configuration used by the examples/next project:
import next from '@presetter/preset-next';
import storybook from '@presetter/preset-storybook';
import { preset } from 'presetter';
export default preset('example-next', {
extends: [next, storybook],
override: {
assets: {
'.storybook/main.ts': {
default: {
framework: '@storybook/nextjs-vite',
},
},
},
},
});
Generated Files & Configurations
.storybook/main.ts (auto-generated)
The preset merges the following into your .storybook/main.ts. Story globs are resolved against your source directory (default src) and kept relative to the Storybook config dir so @storybook/addon-vitest can transform them into Vitest tests:
export default {
stories: ['../src/**/*.stories.@(ts|tsx|js|jsx|mdx)'],
addons: ['@storybook/addon-a11y', '@storybook/addon-vitest'],
};
.storybook/main.ts is added to .gitignore because it is generated during bootstrap.
.storybook/preview.ts (your project)
A preview file enables the a11y addon and turns accessibility findings into test failures. The examples/next project uses:
import addonA11y from '@storybook/addon-a11y';
import { definePreview } from '@storybook/nextjs-vite';
export default definePreview({
parameters: {
a11y: {
test: 'error', // run a11y checks as Vitest assertions
},
},
addons: [addonA11y()],
});
Scripts
| Script | Command | Purpose |
|---|---|---|
storybook | storybook dev -p 6006 | Start the Storybook dev server. |
build:storybook | storybook build | Build a static Storybook. |
pretest:unit:playwright | installs Chromium unless PLAYWRIGHT_READY=1 | Joins the essentials unit steps so Chromium is available before unit tests run. |
pretest:sto | run-s pretest:unit:playwright | Hook of test:sto: installs Chromium before story tests run. |
test:sto | run-s "test:vitest -- --project=STO --project='*(STO)' {@}" -- | Runs story tests only. |
eslint.config.ts (override)
import storybook from 'eslint-plugin-storybook';
export default [
...storybook.configs['flat/recommended'],
{
name: '@presetter/preset-storybook:override:stories',
files: ['**/*.stories.[jt]sx'],
rules: {
'compat/compat': 'off',
},
},
];
vitest.config.ts (override)
The preset adds a headless Chromium browser project so every story is executed as a test:
import { storybookTest } from '@storybook/addon-vitest/vitest-plugin';
import { playwright } from '@vitest/browser-playwright';
export default {
plugins: [storybookTest({ configDir: '.storybook' })],
test: {
globals: true,
browser: {
enabled: true,
headless: true,
provider: playwright(),
instances: [{ browser: 'chromium' }],
},
},
};
Automatic setup files
STO loads .storybook/vitest.setup.ts first when present, then conventional
files detected when the Vitest configuration loads:
| Setting | Bases, in order | Suffixes, in order |
|---|---|---|
setupFiles | vitest.setup, <test>/setup, <test>/vitest.setup | .sto, .story |
globalSetup | vitest.global-setup, <test>/global-setup, <test>/vitest.global-setup | .sto, .story |
<test> is the inherited test variable (default spec). Each base uses the
suffixes above, then extensions ts, mts, cts, js, mjs, cjs.
All matches load in that order. For example:
vitest.setup.sto.tsspec/setup.story.mtsspec/vitest.global-setup.sto.ts
Unsuffixed conventional files belong to UNIT in essentials. User-configured setup files are kept.
Use Cases
- Component documentation — interactive playgrounds for your UI library.
- Story-driven testing — run every story as a Vitest browser test.
- Accessibility gates — fail CI when a story violates a11y rules.
- Design systems — document and verify shared components in isolation.
Variables
| Variable | Default | Description |
|---|---|---|
source | "src" | Directory scanned for *.stories.* files. |
test | "spec" | Directory scanned for conventional setup files. |
Related Presets
@presetter/preset-next— Next.js applications that need Storybook alongside their framework runtime.@presetter/preset-react— React applications with TSX support.@presetter/preset-web— browser globals, TailwindCSS linting, DOM libs, and static asset typings.