Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Vite builder docs a bit #18187

Merged
merged 2 commits into from
May 10, 2022
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 7 additions & 21 deletions docs/builders/vite.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,41 +96,27 @@ If you need, you can also configure Storybook's Vite builder using TypeScript. R

## Troubleshooting

### Prebundle errors
### Working directory not being detected

Vite automatically restarts and begins the prebundling process if it detects a new dependency. This pattern breaks with Storybook and throws confusing error messages. If you see the following message in your terminal:
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These issues have been straightened out in vite 2.9+, and I'd like to avoid the extra confusion that this workaround causes.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@IanVS thanks for clearing this up, appreciate it, looking at the builder's Readme we need to also update it as well to avoid some confusion. I'll follow up with you on this.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep, there are a few things I need to clean up there. 👍

By default, the Vite builder enables Vite's [`server.fs.strict`](https://vitejs.dev/config/#server-fs-strict) option for increased security, defining the project's `root` to Storybook's configuration directory
If you need to override it, you can use the `viteFinal` function and adjust it.

```shell
[vite] new dependencies found:
```
### ArgTypes are not generated automatically

Update your `viteFinal` configuration and include the new dependencies as follows:
Storybook’s [automatic argType inference](https://storybook.js.org/docs/react/api/argtypes#automatic-argtype-inference) is currently only available for React and Vue3 projects. In react projects, if typescript is found in the project's package.json, we assume the components are written in typescript, and use `react-docgen-typescript`. If this causes problems, you can use `react-docgen` by configuring the `typescript` option in your `.storybook/main.js`:
Copy link
Contributor

@jonniebigodes jonniebigodes May 10, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@IanVS we have room for improvement here. We can probably go with:

Currently, [automatic argType inference](../api/argtypes.md#automatic-argtype-inference) is only available for React and Vue3. With React, the Vite builder defaults to `react-docgen-typescript` if TypeScript is listed as a dependency. If you run into any issues, you can revert to `react-docgen` by updating your Storybook configuration file (in `.storybook/main.js|ts`) as follows:


<!-- prettier-ignore-start -->

<CodeSnippets
paths={[
'common/storybook-vite-builder-error-optimized.js.mdx',
'common/storybook-vite-builder-react-docgen.ts.mdx',
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

React and Vue3 projects have automatic docgen. One tricky part is how we choose whether to use typescript or non-typescript docgen for react, so I've expanded on that a bit, with an example of how to configure it.

]}
/>

<!-- prettier-ignore-end -->

### Working directory not being detected

By default, the Vite builder enables Vite's [`server.fs.strict`](https://vitejs.dev/config/#server-fs-strict) option for increased security, defining the project's `root` to Storybook's configuration directory
If you need to override it, you can use the `viteFinal` function and adjust it.

### HMR seems flaky

Saving a component story does not initiate a hot module replacement. Instead, a complete reload happens. You can update your component file or save it to see the changes in effect.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This wasn't quite correct. Changes are always shown, but when editing story files, a reload occurs rather than true HMR. There's a flicker of the screen, but that's about it, and it still usually only takes ~1 second, which is still quite fast.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for clearing that up, appreciate it.


### ArgTypes are not generated automatically

Storybook’s [automatic argType inference](https://storybook.js.org/docs/react/api/argtypes#automatic-argtype-inference) is currently only available for React TypeScript projects. The builder will include additional framework support in future releases.

#### Learn more about builders

- Vite builder for bundling with Vite
- [Webpack builder](./webpack.md) for bundling with Webpack
- [Builder API](./builder-api.md) for building a Storybook builder
- [Builder API](./builder-api.md) for building a Storybook builder
10 changes: 9 additions & 1 deletion docs/snippets/common/storybook-builder-api-dev-server.ts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,19 @@
import { createServer } from 'vite';

export async function createViteServer(options: ExtendedOptions, devServer: Server) {
const { port } = options;
// Remainder server configuration

// Creates the server.
return createServer({
// The server configuration goes here
server: {
middlewareMode: true,
hmr: {
port,
server: devServer,
},
},
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the actual integration between the vite server and storybook dev server, so I think it's important to show it.

});
}
```
```
18 changes: 11 additions & 7 deletions docs/snippets/common/storybook-vite-builder-aliasing.js.mdx
Original file line number Diff line number Diff line change
@@ -1,20 +1,24 @@
```js
// .storybook/main.js|ts
// .storybook/main.js|cjs|ts

const { mergeConfig } = require('vite');

module.exports = {
stories: ['../stories/**/*.stories.mdx', '../stories/**/*.stories.@(js|jsx|ts|tsx)'],
addons: ['@storybook/addon-links', '@storybook/addon-essentials'],
core: {
builder: '@storybook/builder-vite',
},
async viteFinal(config, { configType }) {
// Return the updated configuration
async viteFinal(config) {
// Merge custom configuration into the default config
return mergeConfig(config, {
// Adds a new alias
resolve: {
alias: { exampleAlias: 'something' },
// Use the same "resolve" configuration as your app
resolve: (await import('../vite.config.js')).default.resolve
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is an example of how to re-use configuration between the app's config, and the storybook config, and the resolve setting is something that normally needs to be the same between the two.

// Add dependencies to pre-optimization
optimizeDeps: {
include: ['storybook-dark-mode'],
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When using mergeConfig, it becomes easy to extend the pre-optimized dependencies, so it's nice to show that here.

},
});
},
};
```
```
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,8 @@ module.exports = {
core: {
builder: '@storybook/builder-vite',
},
async viteFinal(config, { configType }) {
config.optimizeDeps.include = [
...(config.optimizeDeps?.include ?? []),
// Other dependencies go here
];
return config;
typescript: {
reactDocgen: 'react-docgen', // 👈 react-docgen configured here.
},
};
```
```