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

Docs: Updates for React Docgen #25776

Merged
merged 8 commits into from
Jan 31, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
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
23 changes: 12 additions & 11 deletions code/builders/builder-vite/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ When installing Storybook, use the `--builder=vite` flag if you do not have a `v

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

Your `vite.config` file will be used by Storybook. If you need to customize the vite config for Storybook, you have two choices:
Your `vite.config` file will be used by Storybook. If you need to customize the Vite config for Storybook, you have two choices:

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.
Expand All @@ -44,12 +44,12 @@ npx storybook@latest 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.
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 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.
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.
8. If you are using `@storybook/addon-interactions`, for now you'll need to add a [workaround](https://github.com/storybookjs/storybook/issues/18399) for jest-mock relying on the node `global` variable by creating a `.storybook/preview-head.html` file containing the following:

```html
Expand All @@ -58,9 +58,9 @@ npx storybook@latest init --builder vite && npm run storybook
</script>
```

9. Start up your storybook using the same `yarn storybook` or `npm run storybook` commands you are used to.
9. Start up your Storybook using the same `yarn storybook` or `npm run storybook` commands you are used to.

For other details about the differences between vite and webpack projects, be sure to read through the [vite documentation](https://vitejs.dev/).
For other details about the differences between Vite and Webpack projects, be sure to read through the [Vite documentation](https://vitejs.dev/).

### Customize Vite config

Expand Down Expand Up @@ -105,7 +105,7 @@ const config = {
export default config;
```

The `viteFinal` function will give you `config` which is the combination of your project's vite config and the builder's own Vite config.
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"`.
Expand Down Expand Up @@ -149,7 +149,7 @@ If you're using TypeScript, we encourage you to experiment and see which option

The builder will by default enable Vite's [server.fs.strict](https://vitejs.dev/config/#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.
Storybook configuration directory. This can be overridden in [viteFinal](https://storybook.js.org/docs/api/main-config-vite-final).

## Known issues

Expand All @@ -158,7 +158,8 @@ 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 3 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.

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!
Expand Down
14 changes: 7 additions & 7 deletions docs/api/arg-types.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,13 +16,13 @@ If you are using the Storybook [docs](../writing-docs/index.md) addon (installed

To do so, Storybook uses various static analysis tools depending on your framework.

| Framework | Static analysis tool |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| React | [react-docgen](https://github.com/reactjs/react-docgen) or [react-docgen-typescript](https://github.com/styleguidist/react-docgen-typescript) |
| Vue 3 | [vue-docgen-api](https://github.com/vue-styleguidist/vue-styleguidist/tree/dev/packages/vue-docgen-api) |
| Angular | [compodoc](https://compodoc.app/) |
| WebComponents | [custom-element.json](https://github.com/webcomponents/custom-elements-json) |
| Ember | [YUI doc](https://github.com/ember-learn/ember-cli-addon-docs-yuidoc#documenting-components) |
| Framework | Static analysis tool |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| React | [react-docgen](https://github.com/reactjs/react-docgen) (default) or [react-docgen-typescript](https://github.com/styleguidist/react-docgen-typescript) |
| Vue | [vue-docgen-api](https://github.com/vue-styleguidist/vue-styleguidist/tree/dev/packages/vue-docgen-api) |
| Angular | [compodoc](https://compodoc.app/) |
| WebComponents | [custom-element.json](https://github.com/webcomponents/custom-elements-json) |
| Ember | [YUI doc](https://github.com/ember-learn/ember-cli-addon-docs-yuidoc#documenting-components) |

The data structure of `argTypes` is designed to match the output of the these tools. Properties specified manually will override what is inferred.

Expand Down
29 changes: 25 additions & 4 deletions docs/api/main-config-typescript.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,32 @@ Parent: [main.js|ts configuration](./main-config.md)

Type:

<IfRenderer renderer='react'>

```ts
{
check?: boolean;
checkOptions?: CheckOptions;
reactDocgen?: 'react-docgen' | 'react-docgen-typescript' | false;
reactDocgenTypescriptOptions?: ReactDocgenTypescriptOptions;
skipCompiler?: boolean;
}
```

</IfRenderer>

<IfRenderer renderer={['angular', 'vue', 'web-components', 'ember', 'html', 'svelte', 'preact', 'qwik','solid' ]}>
jonniebigodes marked this conversation as resolved.
Show resolved Hide resolved

```ts
{
check?: boolean;
checkOptions?: CheckOptions;
skipCompiler?: boolean;
}
```

</IfRenderer>

Configures how Storybook handles [TypeScript files](../configure/typescript.md).

## `check`
Expand Down Expand Up @@ -49,6 +66,8 @@ Options to pass to `fork-ts-checker-webpack-plugin`, if [enabled](#check). See [

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

<IfRenderer renderer='react'>

## `reactDocgen`

Type: `'react-docgen' | 'react-docgen-typescript' | false`
Expand All @@ -58,13 +77,13 @@ Default:
- `false`: if `@storybook/react` is not installed
- `'react-docgen'`: if `@storybook/react` is installed

Only available for React Storybook projects. Configure which library, if any, Storybook uses to parse React components, [react-docgen](https://github.com/reactjs/react-docgen) or [react-docgen-typescript](https://github.com/styleguidist/react-docgen-typescript). Set to `false` to disable parsing React components. `react-docgen-typescript` invokes the TypeScript compiler, which makes it slow but generally accurate. `react-docgen` performs its own analysis, which is much faster but incomplete.
Configures which library, if any, Storybook uses to parse React components, [react-docgen](https://github.com/reactjs/react-docgen) or [react-docgen-typescript](https://github.com/styleguidist/react-docgen-typescript). Set to `false` to disable parsing React components. `react-docgen-typescript` invokes the TypeScript compiler, which makes it slow but generally accurate. `react-docgen` performs its own analysis, which is much faster but incomplete.

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

<CodeSnippets
paths={[
'common/main-config-typescript-react-docgen.ts.mdx',
'react/main-config-typescript-react-docgen.ts.mdx',
]}
/>

Expand All @@ -74,18 +93,20 @@ Only available for React Storybook projects. Configure which library, if any, St

Type: `ReactDocgenTypescriptOptions`

Only available for React Storybook projects. Options to pass to react-docgen-typescript-plugin if react-docgen-typescript is enabled. See [docs for available options](https://github.com/hipstersmoothie/react-docgen-typescript-plugin).
Configures the options to pass to `react-docgen-typescript-plugin` if `react-docgen-typescript` is enabled. See [docs for available options](https://github.com/hipstersmoothie/react-docgen-typescript-plugin).

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

<CodeSnippets
paths={[
'common/main-config-typescript-react-docgen-typescript-options.ts.mdx',
'react/main-config-typescript-react-docgen-typescript-options.ts.mdx',
]}
/>

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

</IfRenderer>

## `skipCompiler`

Type: `boolean`
Expand Down
2 changes: 1 addition & 1 deletion docs/builders/vite.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ If you need to override it, you can use the `viteFinal` function and adjust it.

### ArgTypes are not generated automatically

Currently, [automatic argType inference](../api/arg-types.md#automatic-argtype-inference) is only available for React, Vue 3 and Svelte (JSDocs only). 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 as follows:
Currently, [automatic argType inference](../api/arg-types.md#automatic-argtype-inference) is only available for React, Vue 3, and Svelte (JSDocs only). With React, the Vite builder defaults to `react-docgen`, a faster alternative to `react-docgen-typescript` for parsing React components. If you run into any issues, you can revert to `react-docgen-typescript` by updating your Storybook configuration file as follows:
jonniebigodes marked this conversation as resolved.
Show resolved Hide resolved

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

Expand Down
Loading
Loading