Storybook builder for Vite
Build your stories with vite for fast startup times and near-instant HMR.
Note: This Repository is for Storybook 6.4 and 6.5. In Storybook 7, the Vite builder was brought into the main Storybook monorepo (https://github.com/storybookjs/storybook). See https://storybook.js.org/blog/first-class-vite-support-in-storybook/ for details.
Table of Contents
Installation
Requirements:
- Node 14 - 16 (Node 18 is supported by Storybook 7.0)
- Vite 4.0 or newer (for Vite v3, use
@storybook/[email protected]) - Storybook 6.4 or 6.5 (for storybook 7, see https://github.com/storybookjs/storybook/tree/next/code/lib/builder-vite)
npm install @storybook/builder-vite --save-devor
yarn add --dev @storybook/builder-viteor
pnpm add --save-dev @storybook/builder-viteNote: when using pnpm, you may need to enable shamefully-hoist, until #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.tsxor.stories.jsxfile suffix. See also #53
The builder supports both development mode in Storybook, and building a static production version.
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
Migration from webpack / CRA
- Install
viteand@storybook/builder-vite - Remove any explicit project dependencies on
webpack,react-scripts, and any other webpack plugins or loaders. - If you were previously using
@storybook/manager-webpack5, you'll need to remove it, since currently the vite builder only works withmanager-webpack4, which is the default and does not need to be installed manually. Also remove@storybook/builder-webpack5or@storybook/builder-webpack4if they are installed. - Set
core: { builder: "@storybook/builder-vite" }in your.storybook/main.jsfile. - Remove storybook webpack cache (
rm -rf node_modules/.cache) - Update your
/public/index.htmlfile for vite (be sure there are no%PUBLIC_URL%inside it, which is a CRA variable) - Be sure that any files containing JSX syntax use a
.jsxor.tsxfile extension, which vite requires. This includes.storybook/preview.jsxif it contains JSX syntax. - If you are using
@storybook/addon-interactions, for now you'll need to add a workaround for jest-mock relying on the nodeglobalvariable by creating a.storybook/preview-head.htmlfile containing the following:
<script>
window.global = window;
</script>- Start up your storybook using the same
yarn storybookornpm run storybookcommands you are used to.
For other details about the differences between vite and webpack projects, be sure to read through the vite documentation.
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 svelte.config.js file will be used automatically.
If you need to make overrides for Storybook, 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.
Known issues
- HMR: saving a story file does not hot-module-reload, a full reload happens instead. HMR works correctly when saving component files.
Migration from storybook-builder-vite
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 automigrateTo manually migrate:
- Remove
storybook-builder-vitefrom yourpackage.jsondependencies - Install
@storybook/builder-vite - Update your
core.buildersetting in.storybook/main.jsto@storybook/builder-vite.
Contributing
The Vite builder cannot build itself. Are you willing to contribute? We are especially looking for vue and svelte experts, as the current maintainers are react users.
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.