@storybook/builder-vite

What is @storybook/builder-vite?

The @storybook/builder-vite package is a Storybook builder that integrates Vite as the build tool for Storybook. It allows developers to leverage Vite's fast build times and features within their Storybook environment. This package is particularly useful for projects that are already using Vite and want to maintain consistency in their build tools.

What are @storybook/builder-vite's main functionalities?

Custom Vite Configuration

Allows customization of the Vite configuration used by Storybook. Developers can add aliases, plugins, and modify other settings to tailor the build process.

module.exports = {
  stories: ['../stories/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
  addons: ['@storybook/addon-links', '@storybook/addon-essentials'],
  core: {
    builder: '@storybook/builder-vite'
  },
  async viteFinal(config, { configType }) {
    // customize the Vite config here
    config.resolve.alias = {
      ...config.resolve.alias,
      '@components': '/path/to/components'
    };
    // return the customized config
    return config;
  }
};

Fast Build Times

By using Vite as the build tool, Storybook can take advantage of Vite's fast build times, leading to quicker startup and refresh times during development.

// There is no specific code sample for this feature as it is an inherent benefit of using Vite with Storybook.

Support for Vite Plugins

Enables the use of Vite plugins within the Storybook build process, allowing developers to extend functionality with Vite's rich plugin ecosystem.

module.exports = {
  core: {
    builder: '@storybook/builder-vite'
  },
  async viteFinal(config) {
    config.plugins.push(myVitePlugin());
    return config;
  }
};

Other packages similar to @storybook/builder-vite

@storybook/builder-webpack5

This package is a Storybook builder that uses Webpack 5 as the build tool. It is similar to @storybook/builder-vite in that it integrates a modern build tool into Storybook, but it uses Webpack instead of Vite. Webpack is more established but generally has slower build times compared to Vite.

@storybook/builder-webpack4

Similar to the webpack5 builder, this package integrates Webpack 4 into Storybook. It is for projects that are still using Webpack 4 and have not yet upgraded to Webpack 5. It offers a different set of features and plugin compatibility compared to Vite.

@storybook/addon-storyshots

While not a builder, this addon provides snapshot testing for Storybook stories. It complements builders like @storybook/builder-vite by adding testing capabilities to the development workflow.

README

Storybook builder for Vite

Build your stories with vite for fast startup times and near-instant HMR.

Table of Contents

• Migration from storybook-builder-vite
• Installation
• Usage
  • Customize Vite Config
  • Svelte Customization
  • TypeScript
  • React Docgen
  • Working Directory
• How to Start a New Project
• Known issues
• Contributing

Project has been renamed

This project has moved from storybook-builder-vite to @storybook/builder-vite as part of a larger effort to improve Vite support in Storybook. To automatically migrate your existing project, you can run

npx sb@next automigrate

To manually migrate:

1. Remove storybook-builder-vite from your package.json dependencies
2. Install @storybook/builder-vite
3. Update your core.builder setting in .storybook/main.js to @storybook/builder-vite.

Installation

Requirements:

• Vite 2.5 or newer
• Storybook 6.4.0 or newer (for storybook 6.3, use storybook-builder-vite@0.1.16)

npm install @storybook/builder-vite --save-dev

or

yarn add --dev @storybook/builder-vite

or

pnpm add --save-dev @storybook/builder-vite

Note: when using pnpm, you may need to enable shamefully-hoist, until https://github.com/storybookjs/builder-vite/issues/55 can be fixed.

Usage

In your main.js configuration file, set core: { builder: "@storybook/builder-vite" }.

For autoreload of react stories to work, they need to have a .stories.tsx or .stories.jsx file suffix. See also #53

The builder supports both development mode in Storybook, and building a static production version.

If you were previously using @storybook/manager-webpack5, you'll need to remove it, since currently the vite builder only works with manager-webpack4, which is the default and does not need to be installed manually.

Customize Vite config

The builder will not read your vite.config.js file by default.

In .storybook/main.js (or whatever your Storybook config file is named) you can override the Vite config:

// use `mergeConfig` to recursively merge Vite options
const { mergeConfig } = require('vite');

module.exports = {
  async viteFinal(config, { configType }) {
    // return the customized config
    return mergeConfig(config, {
      // customize the Vite config here
      resolve: {
        alias: { foo: 'bar' },
      },
    });
  },
  // ... other options here
};

The viteFinal function will give you config which is the builder's own Vite config. You can tweak this as you want, for example to set up aliases, add new plugins etc.

The configType variable will be either "DEVELOPMENT" or "PRODUCTION".

The function should return the updated Vite configuration.

Svelte Customization

When using this builder with Svelte, your .storybook/main.js (or equivalent) can contain a svelteOptions object to pass custom options to vite-plugin-svelte:

const preprocess = require('svelte-preprocess');

module.exports = {
  svelteOptions: {
    preprocess: preprocess({
      typescript: true,
      postcss: true,
      sourceMap: true,
    }),
  },
};

TypeScript

Configure your .storybook/main.ts to use TypeScript:

import type { StorybookViteConfig } from '@storybook/builder-vite';

const config: StorybookViteConfig = {
  // other storybook options...,
  async viteFinal(config, options) {
    // modify and return config
  },
};

export default config;

Or alternatively, you can use named exports:

import type { ViteFinal } from '@storybook/builder-vite';

export const viteFinal: ViteFinal = async (config, options) => {
  // modify and return config
};

See Customize Vite config for details about using viteFinal.

React Docgen

Docgen is used in Storybook to populate the props table in docs view, the controls panel, and for several other addons. Docgen is supported in vue and react, and there are two docgen options when using react, react-docgen and react-docgen-typescript. You can learn more about the pros/cons of each in this gist. By default, if we find a typescript dependency in your package.json file, we will assume you're using typescript and will choose react-docgen-typescript. You can change this by setting the typescript.reactDocgen option in your .storybook/main.js file:

module.exports = {
  typescript: {
    reactDocgen: 'react-docgen`
  }
}

If you're using TypeScript, we encourage you to experiment and see which option works better for your project.

Note about working directory

The builder will by default enable Vite's server.fs.strict option, for increased security. The default project root is set to the parent directory of the storybook configuration directory. This can be overridden in viteFinal.

Getting started with Vite and Storybook (on a new project)

See https://vitejs.dev/guide/#scaffolding-your-first-vite-project,

npm create vite@latest # follow the prompts
npx sb init --builder @storybook/builder-vite && npm run storybook

Known issues

• HMR: saving a story file does not hot-module-reload, a full reload happens instead. HMR works correctly when saving component files.
• Prebundling: Vite restarts if it detects new dependencies which it did not know about and needs to pre-bundle. This breaks within storybook, with confusing error messages. If you see a message in your terminal like [vite] new dependencies found:, please add those dependencies to your optimizeDeps.include in viteFinal. E.g. config.optimizeDeps.include = [...(config.optimizeDeps?.include ?? []), "storybook-dark-mode"],. Vite 2.9.0+ may improve this behavior.

Contributing

The Vite builder cannot build itself. Are you willing to contribute?

https://github.com/storybookjs/builder-vite/issues/11

Have a look at the GitHub issues for known bugs. If you find any new bugs, feel free to create an issue or send a pull request!

Please read the How to contribute guide.

About this codebase

The code is a monorepo with the core @storybook/builder-vite package, and examples (like examples/react) to test the builder implementation.

Similar to the main storybook monorepo, you need yarn to develop this builder, because the project is organized as yarn workspaces. This lets you write new code in the core builder package, and instantly use them from the example packages.