mirror of
https://github.com/storybookjs/storybook.git
synced 2025-04-06 01:51:05 +08:00
Docs: Update Vite builder README
This commit is contained in:
Ian VanSchooten
parent
af0578d99c
commit
d230ec35dd
@ -4,68 +4,34 @@ Build your stories with [vite](https://vitejs.dev/) for fast startup times and n
|
||||
|
||||
# Table of Contents <!-- omit in toc -->
|
||||
|
||||
- [Migration from storybook-builder-vite](#migration-from-storybook-builder-vite)
|
||||
- [Installation](#installation)
|
||||
- [Usage](#usage)
|
||||
- [Getting started with Vite and Storybook (on a new project)](#getting-started-with-vite-and-storybook-on-a-new-project)
|
||||
- [Migration from webpack / CRA](#migration-from-webpack--cra)
|
||||
- [Customize Vite config](#customize-vite-config)
|
||||
- [Svelte Customization](#svelte-customization)
|
||||
- [Svelte Options](#svelte-options)
|
||||
- [TypeScript](#typescript)
|
||||
- [React Docgen](#react-docgen)
|
||||
- [Note about working directory](#note-about-working-directory)
|
||||
- [Known issues](#known-issues)
|
||||
- [Contributing](#contributing)
|
||||
- [About this codebase](#about-this-codebase)
|
||||
|
||||
## 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
|
||||
|
||||
```bash
|
||||
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 3.0 or newer (for Vite v2 (2.5+), use `@storybook/builder-vite@0.1.x`)
|
||||
- Storybook 6.4.0 or newer (for storybook 6.3, use `storybook-builder-vite@0.1.16`)
|
||||
- Vite 3.0 or newer (4.X recommended)
|
||||
|
||||
```bash
|
||||
npm install @storybook/builder-vite --save-dev
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```bash
|
||||
yarn add --dev @storybook/builder-vite
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```bash
|
||||
pnpm add --save-dev @storybook/builder-vite
|
||||
```
|
||||
|
||||
Note: when using `pnpm`, you may need to enable [shamefully-hoist](https://pnpm.io/npmrc#shamefully-hoist), until https://github.com/storybookjs/builder-vite/issues/55 can be fixed.
|
||||
When installing Storybook, use the `--builder=vite` flag if you do not have a `vite.config` file at your project root (if you do, the vite builder is chosen automatically).
|
||||
|
||||
## Usage
|
||||
|
||||
In your `main.js` configuration file,
|
||||
set `core: { builder: "@storybook/builder-vite" }`.
|
||||
The builder supports both development mode in Storybook and building a static production version.
|
||||
|
||||
> For autoreload of react stories to work, they need to have a `.stories.tsx` or `.stories.jsx` file suffix.
|
||||
> See also [#53](https://github.com/storybookjs/builder-vite/pull/53)
|
||||
Your `vite.config` file will be used by Storybook. If you need to customize the vite config for Storybook, you have two choices:
|
||||
|
||||
The builder supports both development mode in Storybook, and building a static production version.
|
||||
1. Set values in your `vite.config` conditionally, based on an environment variable, for example.
|
||||
2. Add a `viteFinal` config to your `.storybook/main.js` file. See [Customize Vite config](#customize-vite-config) for details.
|
||||
|
||||
### Getting started with Vite and Storybook (on a new project)
|
||||
|
||||
@ -73,15 +39,15 @@ 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
|
||||
npx sb@next init --builder vite && npm run storybook
|
||||
```
|
||||
|
||||
### Migration from webpack / CRA
|
||||
|
||||
1. Install `vite` and `@storybook/builder-vite`
|
||||
2. Remove any explicit project dependencies on `webpack`, `react-scripts`, and any other webpack plugins or loaders.
|
||||
3. 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. Also remove `@storybook/builder-webpack5` or `@storybook/builder-webpack4` if they are installed.
|
||||
4. Set `core: { builder: "@storybook/builder-vite" }` in your `.storybook/main.js` file.
|
||||
3. If you were previously using `@storybook/manager-webpack5`, you can remove it. Also remove `@storybook/builder-webpack5` or `@storybook/builder-webpack4` if they are installed.
|
||||
4. Choose a vite-based Storybook "framework" to set in the `framework` option of your `.storybook/main.js` file.
|
||||
5. Remove storybook webpack cache (`rm -rf node_modules/.cache`)
|
||||
6. Update your `/public/index.html` file for vite (be sure there are no `%PUBLIC_URL%` inside it, which is a CRA variable)
|
||||
7. Be sure that any files containing JSX syntax use a `.jsx` or `.tsx` file extension, which [vite requires](https://vitejs.dev/guide/features.html#jsx). This includes `.storybook/preview.jsx` if it contains JSX syntax.
|
||||
@ -99,65 +65,48 @@ For other details about the differences between vite and webpack projects, be su
|
||||
|
||||
### Customize Vite config
|
||||
|
||||
The builder will _not_ read your `vite.config.js` file by default.
|
||||
The builder _will_ read your `vite.config.js` file, though it may change some of the options in order to work correctly.
|
||||
|
||||
In `.storybook/main.js` (or whatever your Storybook config file is named)
|
||||
you can override the Vite config:
|
||||
In `.storybook/main.js` (or whatever your Storybook config file is named), you can override the merged Vite config:
|
||||
|
||||
```javascript
|
||||
// use `mergeConfig` to recursively merge Vite options
|
||||
const { mergeConfig } = require('vite');
|
||||
import { mergeConfig } from 'vite';
|
||||
|
||||
module.exports = {
|
||||
const config: StorybookConfig = {
|
||||
async viteFinal(config, { configType }) {
|
||||
// return the customized config
|
||||
// Be sure to return the customized config
|
||||
return mergeConfig(config, {
|
||||
// customize the Vite config here
|
||||
// Customize the Vite config for Storybook
|
||||
resolve: {
|
||||
alias: { foo: 'bar' },
|
||||
},
|
||||
});
|
||||
},
|
||||
// ... other options here
|
||||
};
|
||||
|
||||
export default config;
|
||||
```
|
||||
|
||||
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 `viteFinal` function will give you `config` which is the combination of your project's vite config and 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
|
||||
### Svelte Options
|
||||
|
||||
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`](https://github.com/sveltejs/vite-plugin-svelte/tree/main/packages/vite-plugin-svelte):
|
||||
|
||||
```javascript
|
||||
const preprocess = require('svelte-preprocess');
|
||||
|
||||
module.exports = {
|
||||
svelteOptions: {
|
||||
preprocess: preprocess({
|
||||
typescript: true,
|
||||
postcss: true,
|
||||
sourceMap: true,
|
||||
}),
|
||||
},
|
||||
};
|
||||
```
|
||||
When using this builder with Svelte, your `svelte.config.js` file will be used automatically.
|
||||
|
||||
### TypeScript
|
||||
|
||||
Configure your `.storybook/main.ts` to use TypeScript:
|
||||
|
||||
```typescript
|
||||
import type { StorybookViteConfig } from '@storybook/builder-vite';
|
||||
import type { StorybookConfig } from '@storybook/react-vite'; // (or whatever framework you are using)
|
||||
|
||||
const config: StorybookViteConfig = {
|
||||
const config: StorybookConfig = {
|
||||
// other storybook options...,
|
||||
async viteFinal(config, options) {
|
||||
// modify and return config
|
||||
@ -181,7 +130,7 @@ See [Customize Vite config](#customize-vite-config) for details about using `vit
|
||||
|
||||
### 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](https://gist.github.com/shilman/036313ffa3af52ca986b375d90ea46b0). 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:
|
||||
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 Svelte, 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](https://gist.github.com/shilman/036313ffa3af52ca986b375d90ea46b0). 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:
|
||||
|
||||
```javascript
|
||||
module.exports = {
|
||||
@ -206,20 +155,9 @@ storybook configuration directory. This can be overridden in viteFinal.
|
||||
## 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.
|
||||
Are you willing to contribute? We are especially looking for Vue and Svelte experts, as the current maintainers are react users.
|
||||
|
||||
https://github.com/storybookjs/builder-vite/issues/11
|
||||
|
||||
Have a look at the GitHub issues for known bugs. If you find any new bugs,
|
||||
Have a look at the GitHub issues with the `vite` label 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](/CONTRIBUTING.md) 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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user