Storybook for SolidJS

Community supported Storybook framework adapter for SolidJS, using Vite as the bundler.

📋 Table of Contents

• Storybook for SolidJS
  • 📋 Table of Contents
  • ✨ Features
  • 🚀 Getting Started
  • 📦 Manual Installation
  • ⚙️ Configuration
  • 🔄 Migration Guide
  • 🤝 Contributing
  • 👤 Maintainer
  • 📖 License

✨ Features

• Fast Vite-powered — Lightning-fast Storybook experience using Vite.
• SolidJS Native — Out-of-the-box support for Solid components and JSX.
• Latest Storybook Support — Built for and tested with the newest Storybook version.
• TypeScript-First — Full TypeScript support for your components and stories.
• Addon Ecosystem — Works with popular Storybook addons (Docs, Controls, Actions, Links, etc.).
• ArgTypes from TypeScript — Prop tables and controls generated directly from your TypeScript types.
• Integrated Testing — Built-in support for component and story testing with Vitest and Playwright.
• Hot Reload — Instant updates as you edit components, powered by Vite.
• MDX & Docs — Write rich documentation alongside your stories using MDX.
• Accessibility (a11y) — Built-in accessibility checks for your components.

🚀 Getting Started

The fastest way to start using Storybook with SolidJS:

npx create-solid-storybook <folder-name>

Replace <folder-name> with your desired project directory name. This will generate a SolidJS project pre-configured with Storybook 9 and all essential addons.

Then run:

cd <folder-name>
npm run storybook

Open the provided URL in your browser to view your Storybook instance.

📦 Manual Installation

You can set everything up manually. To do this:

1. Copy the following files from storybook-solid-template to your project:

• .storybook/**
• vitest.config.ts

2. Install the required dependencies:

npm install storybook storybook-solidjs-vite @chromatic-com/storybook @storybook/addon-onboarding @storybook/addon-docs @storybook/addon-a11y @storybook/addon-links @storybook/addon-vitest @vitest/coverage-v8 playwright vitest @vitest/browser

3. Add the necessary scripts to your package.json:

"scripts": {
  "build": "storybook build",
  "storybook": "storybook dev -p 6006"
}

4. Create your stories in stories/ (or use examples from the template's stories folder)

5. Start Storybook:

npm run storybook

⚙️ Configuration

• You can customize Vite and Storybook as usual. For advanced configuration, see the Storybook Vite docs.
• Add your stories in src/**/*.stories.tsx or src/**/*.stories.js.
• Use Storybook Addons for extra features.

🎨 Decorators

createDecorator and createJSXDecorator helpers

Storybook re-executes decorator code and story code on every change (e.g., when args or globals change). However, SolidJS uses fine-grained reactivity, which means components run once and effects/tracking scopes re-run when dependencies change. SolidJS doesn't require re-executing the component function itself on every update.

This mismatch causes issues: when decorators that return JSX are re-executed, they create duplicate DOM elements, leading to double-rendering. The createJSXDecorator helper marks decorators so they're only executed once, preventing this issue.

Use createDecorator for decorators that don't return JSX (e.g., they only call Story()). This ensures type safety only.

Use createJSXDecorator for decorators that return JSX elements. This ensures type safety and prevents double-rendering by marking them to be executed only once on initial render.

Example: Decorator that returns JSX

import { createJSXDecorator } from 'storybook-solidjs-vite';

export const solidDecorator = createJSXDecorator((Story, context) => {
  return (
    <main>
      <Story />
    </main>
  );
});

Example: Decorator that doesn't return JSX

import { createDecorator } from 'storybook-solidjs-vite';

export const regularDecorator = createDecorator((Story) => {
  return Story();
});

Manual Flag Assignment

You can also manually mark decorators as JSX-returning by setting the flag directly:

import { IS_SOLID_JSX_FLAG } from 'storybook-solidjs-vite';

export const myDecorator = (Story, context) => {
  return <div><Story /></div>;
};

myDecorator[IS_SOLID_JSX_FLAG] = true;

🔄 Migration Guide

Migrating from version 9 to 10? Check out our Migration Guide for step-by-step instructions and breaking changes.

🤝 Contributing

Contributions, issues and feature requests are welcome! Feel free to open an issue or submit a PR.

👤 Maintainer

Maintained with ❤️ by @kachurun

📖 License

MIT