diff --git a/code/builders/builder-vite/README.md b/code/builders/builder-vite/README.md index 02532578fcad..18a2e0ec6df3 100644 --- a/code/builders/builder-vite/README.md +++ b/code/builders/builder-vite/README.md @@ -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. @@ -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 @@ -58,9 +58,9 @@ npx storybook@latest init --builder vite && npm run storybook ``` -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 @@ -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"`. @@ -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 @@ -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! diff --git a/docs/api/arg-types.md b/docs/api/arg-types.md index ce52bad09f84..ed9f66b4cdd0 100644 --- a/docs/api/arg-types.md +++ b/docs/api/arg-types.md @@ -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. diff --git a/docs/api/main-config-typescript.md b/docs/api/main-config-typescript.md index ae25c4fb308a..9af77907c54c 100644 --- a/docs/api/main-config-typescript.md +++ b/docs/api/main-config-typescript.md @@ -6,15 +6,32 @@ Parent: [main.js|ts configuration](./main-config.md) Type: + + ```ts { check?: boolean; checkOptions?: CheckOptions; reactDocgen?: 'react-docgen' | 'react-docgen-typescript' | false; reactDocgenTypescriptOptions?: ReactDocgenTypescriptOptions; + skipCompiler?: boolean; } ``` + + + + +```ts +{ + check?: boolean; + checkOptions?: CheckOptions; + skipCompiler?: boolean; +} +``` + + + Configures how Storybook handles [TypeScript files](../configure/typescript.md). ## `check` @@ -49,6 +66,8 @@ Options to pass to `fork-ts-checker-webpack-plugin`, if [enabled](#check). See [ + + ## `reactDocgen` Type: `'react-docgen' | 'react-docgen-typescript' | false` @@ -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. @@ -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). + + ## `skipCompiler` Type: `boolean` diff --git a/docs/builders/vite.md b/docs/builders/vite.md index 69bd64d147a3..a254e7b5f7a0 100644 --- a/docs/builders/vite.md +++ b/docs/builders/vite.md @@ -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: diff --git a/docs/configure/typescript.md b/docs/configure/typescript.md index eb789ed833e7..cbbfccd4833d 100644 --- a/docs/configure/typescript.md +++ b/docs/configure/typescript.md @@ -28,20 +28,50 @@ See the Vite builder [TypeScript documentation](https://github.com/storybookjs/b ### Extending the default configuration -Out of the box, Storybook is built to work with a wide range of third-party libraries, enabling you to safely access and document metadata (e.g., props, inputs) from your components without any additional configuration. Since Storybook supports multiple frameworks, it also includes a set of third-party packages to support each framework (e.g., `ts-loader` and `ngx-template-loader` for Angular, `react-docgen-typescript-plugin` for React). If you need to customize the default configuration for a specific use case scenario, refer to the [`config.typescript` API reference](../api/main-config-typescript.md). + -The above example extends the baseline configuration to remove existing props from third-party libraries. Useful if you want to document only your components. However, if you need to include them, you can do so by adjusting your configuration as follows: +Out of the box, Storybook is built to work with a wide range of third-party libraries, enabling you to safely access and document metadata (e.g., props, inputs) from your components without any additional configuration. Since Storybook supports multiple frameworks, it also includes a set of third-party packages to support each framework (e.g., `ts-loader`, `vue-docgen-api` for Vue). If you need to customize the default configuration for a specific use case scenario, you can adjust your Storybook configuration file and provide the required options. Listed below are the available options and examples of how to use them. + +| Option | Description | +| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `check` | Available for Webpack-based projects.
Enables type checking within Storybook
`typescript: { check: true },` | +| `checkOptions` | Requires the `check` option to be enabled.
Configures the [`fork-ts-checker-webpack-plugin`](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin) plugin
`typescript: { checkOptions:{},},` | +| `skipCompiler` | Disables parsing Typescript files through the compiler
`typescript: { skipCompiler:false,},` | + + + + + +Out of the box, Storybook is built to work with a wide range of third-party libraries, enabling you to safely access and document metadata (e.g., props) for your components without any additional configuration. It relies on [`react-docgen`](https://github.com/reactjs/react-docgen), a fast and highly customizable parser to process TypeScript files to infer the component's metadata and generate types automatically for improved performance and type safety. If you need to customize the default configuration for a specific use case scenario, you can adjust your Storybook configuration file and provide the required options. Listed below are the available options and examples of how to use them. + +| Option | Description | +| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `check` | Available for Webpack-based projects.
Enables type checking within Storybook
`typescript: { check: true },` | +| `checkOptions` | Requires the `check` option to be enabled.
Configures the [`fork-ts-checker-webpack-plugin`](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin) plugin
`typescript: { checkOptions: {},},` | +| `reactDocgen` | Configures the TypeScript parser used by Storybook.
Available options: `react-docgen` (default), `react-docgen-typescript`,` false`
`typescript: { reactDocgen: 'react-docgen'},` | +| `reactDocgenTypescriptOptions` | Requires the `reactDocgen`option to be `react-docgen-typescript`.
Configures the `react-docgen-typescript-plugin` plugin per builder
`typescript: { reactDocgen: 'react-docgen-typescript', reactDocgenTypescriptOptions: {},},` | +| `skipCompiler` | Disables parsing Typescript files through the compiler
`typescript: { skipCompiler:false,},` | + + + + + +Additional options are available for the `typescript` configuration option. See the [`config.typescript` API reference](../api/main-config-typescript.md) for more information. + + + ## Write stories with TypeScript Storybook provides zero-config TypeScript support, allowing you to write stories using this language without additional configuration. You can use this format for improved type safety and code completion. For example, if you're testing a `Button` component, you could do the following in your story file: @@ -92,6 +122,45 @@ Now, when you define a story or update an existing one, you'll automatically get Out of the box, Storybook supports the `satisfies` operator for almost every framework already using TypeScript version 4.9 or higher. However, due to the constraints of the Angular and Web Components framework, you might run into issues when applying this operator for additional type safety. This is primarily due to how both frameworks are currently implemented, making it almost impossible for Storybook to determine if the component property is required. If you encounter this issue, please open up a support request on [GitHub Discussions](https://github.com/storybookjs/storybook/discussions/new?category=help). + + ### The TypeScript auto-completion is not working on my editor If you're using Vue single file components and TypeScript, you can add both [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) and the [TypeScript Vue Plugin](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin) for editor support, additional type safety and auto-completion. Nevertheless, if you're working with Svelte, you can add the [Svelte for VSCode extension](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode) for similar benefits. + + + + + +### Storybook doesn't create the required types for external packages + +If your project relies on a third-party library and the expected types are not being generated, preventing you from accurately documenting your components, you can adjust the `reactDocgen` configuration option in your Storybook configuration file to use `react-docgen-typescript` instead and include the required options. For example: + + + + + + + + +### The types are not being generated for my component + +If you're working with a React project, type inference is automatically enabled for your components using the `react-docgen` library for improved build times and type safety. However, you may run into a situation where some options may not work as expected (e.g., [`Enums`](https://www.typescriptlang.org/docs/handbook/enums.html), React's [`forwardRef`](https://react.dev/reference/react/forwardRef)). This is primarily due to how the `react-docgen` package is implemented, making it difficult for Storybook to infer the component's metadata and generate types automatically. To solve this, you can update the `typescript` configuration option in your Storybook configuration file to use `react-docgen-typescript` instead. For example: + + + + + + + +If you're still encountering issues, we recommend reaching out to the community using the default communication channels (e.g., [GitHub discussions](https://github.com/storybookjs/storybook/discussions/new?category=help)). + + diff --git a/docs/essentials/controls.md b/docs/essentials/controls.md index 67b65cb7f51e..60c950c34d29 100644 --- a/docs/essentials/controls.md +++ b/docs/essentials/controls.md @@ -31,7 +31,49 @@ If you have stories in the older pre-Storybook 6 style, check the [args & contro -By default, Storybook will choose a control for each arg based on its initial value. This will work well with specific arg types (e.g., `boolean` or `string`). To enable them, add the `component` annotation to the default export of your story file, and it will be used to infer the controls and auto-generate the matching [`argTypes`](../api/arg-types.md) for your component using [Compodoc](https://compodoc.app/) if you opt-in to use it, including first-class support for Angular's `inputs`, `outputs`, `properties`, `methods` and `view/content child/children`. +By default, Storybook will try to infer the required argTypes and associated controls for your stories based on the component's definition and initial value of the args using [Compodoc](https://compodoc.app/), a documentation generator for Angular applications that can extract the metadata of your components, including first-class support for Angular's `inputs`, `outputs`, `properties`, `methods`, and `view/content child/children`. If you opt-in to use it, you must take additional steps to set it up properly. + +Run the following command to install the tooling. + + + + + + + +Update your `angular.json` file to include the following configuration to include it in the Storybook's inbuilt builder configuration. + + + + + + + + +Finally, update your `.storybook/preview.ts` file to include the following configuration to import the metadata generated by Compodoc and use it to generate the controls and argTypes for your stories. + + + + + + + + +When you set the `component` annotation of the default export of your story file, it will be used to infer the controls and auto-generate the matching [`argTypes`](../api/arg-types.md) for your component. @@ -45,9 +87,57 @@ By default, Storybook will choose a control for each arg based on its initial va + + +By default, Storybook will try to infer the required argTypes and associated controls for your stories based on the metadata provided by the [`@storybook/ember-cli-storybook`](https://github.com/storybookjs/ember-cli-storybook) adapter. You'll need to take some additional steps to set it up properly. + +Update your `ember-cli-build.js` configuration file to include the adapter. + + + + + + + +Restart your application to generate the metadata file (i.e., `storybook-docgen/index.json`) and update your `.storybook/preview.js` file to include it, which will be used to create the controls and argTypes for your stories. + + + + + + + + + +Enabling this feature will generate a `storybook-docgen/index.json` automatically with each build. For more information on how the metadata is generated, refer to [documentation](https://github.com/storybookjs/storybook/tree/next/code/frameworks/ember) for the Ember framework. + + + +When you set the `component` annotation of the default export of your story file, it will be used to infer the controls and auto-generate the matching [`argTypes`](../api/arg-types.md) for your component. + + + + + + + + + -By default, Storybook will choose a control for each arg based on its initial value. This will work well with specific arg types (e.g., `boolean` or `string`). To enable them, add the `component` annotation to the default export of your story file and it will be used to infer the controls and auto-generate the matching [`argTypes`](../api/arg-types.md) for your component using [`react-docgen`](https://github.com/reactjs/react-docgen) or [`react-docgen-typescript`](https://github.com/styleguidist/react-docgen-typescript) for TypeScript. +By default, Storybook will choose a control for each arg based on its initial value. This will work well with specific arg types (e.g., `boolean` or `string`). To enable them, add the `component` annotation to the default export of your story file, and it will be used to infer the controls and auto-generate the matching [`argTypes`](../api/arg-types.md) for your component using [`react-docgen`](https://github.com/reactjs/react-docgen), a documentation generator for React components that also includes first-class support for TypeScript. @@ -79,7 +169,38 @@ By default, Storybook will choose a control for each arg based on its initial va - + + +By default, Storybook will try to infer the required argTypes and associated controls for your stories based on the component's definition and the initial value of the args. You'll need to take some additional steps to set it up properly. You can opt to generate a [`custom-elements.json`](https://github.com/webcomponents/custom-elements-json) file with [`@custom-elements-manifest/analyzer`](https://github.com/open-wc/custom-elements-manifest) if you're using the `pre-v1.0.0` version of the elements file or [`@custom-elements-manifest/analyzer`](https://github.com/open-wc/custom-elements-manifest/tree/master/packages/analyzer) for newer versions and configure it in your Storybook UI configuration file (i.e., `.storybook/preview.js|ts`) to enable it. + + + + + + + + +When you set the `component` annotation of the default export of your story file, it will be used to infer the controls and auto-generate the matching [`argTypes`](../api/arg-types.md) for your component. + + + + + + + + + + By default, Storybook will choose a control for each arg based on its initial value. This will work well with specific arg types (e.g., `boolean` or `string`). To enable them, add the `component` annotation to the default export of your story file, and it will be used to infer the controls and auto-generate the matching [`argTypes`](../api/arg-types.md) for your component provided by the framework you've chosen to use. @@ -87,17 +208,16 @@ By default, Storybook will choose a control for each arg based on its initial va + + If you're using a framework that doesn't support this feature, you'll need to define the `argTypes` for your component [manually](#fully-custom-args). @@ -163,10 +283,10 @@ This replaces the input with a radio group for a more intuitive experience. Controls can automatically be inferred from arg's name with [regex](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RegExp), but currently only for the color picker and date picker controls. If you've used the Storybook CLI to setup your project, it should have automatically created the following defaults in `.storybook/preview.js`: -| Control | Default regex | Description | -| :-------: | :--------------------------------------: | :-------------------------------------------------------: | +| Control | Default regex | Description | +| --------- | ---------------------------------------- | --------------------------------------------------------- | | **color** | /(background|color)$/i | Will display a color picker UI for the args that match it | -| **date** | `/Date$/` | Will display a date picker UI for the args that match it | +| **date** | `/Date$/` | Will display a date picker UI for the args that match it | If you haven't used the CLI to set the configuration, or if you want to define your patterns, use the `matchers` property in the `controls` parameter: @@ -221,9 +341,9 @@ Using `argTypes`, you can change the display and behavior of each control. ### Dealing with complex values -When dealing with non-primitive values, you'll notice that you'll run into some limitations. The most obvious issue is that not every value can be represented as part of the `args` param in the URL, losing the ability to share and deeplink to such a state. Beyond that, complex values such as JSX cannot be synchronized between the manager (e.g., Controls addon) and the preview (your story). +When dealing with non-primitive values, you'll notice that you'll run into some limitations. The most obvious issue is that not every value can be represented as part of the `args` param in the URL, losing the ability to share and deep link to such a state. Beyond that, complex values such as JSX cannot be synchronized between the manager (e.g., Controls addon) and the preview (your story). -One way to deal with this is to use primitive values (e.g., strings) as arg values and add a custom `render` function to convert these values to their complex counterpart before rendering. It isn't the nicest way to do it (see below), but certainly the most flexible. +One way to deal with this is to use primitive values (e.g., strings) as arg values and add a custom `render` function to convert them to their complex counterpart before rendering. It isn't the nicest way to do it (see below), but certainly the most flexible. @@ -282,7 +402,7 @@ As shown above, you can configure individual controls with the “control" annot | **number** | `number` | Provides a numeric input to include the range of all possible values.
`argTypes: { even: { control: { type: 'number', min:1, max:30, step: 2 } }}` | | | `range` | Provides a range slider component to include all possible values.
`argTypes: { odd: { control: { type: 'range', min: 1, max: 30, step: 3 } }}` | | **object** | `object` | Provides a JSON-based editor component to handle the object's values.
Also allows edition in raw mode.
`argTypes: { user: { control: 'object' }}` | -| **array** | `object` | Provides a JSON-based editor component to handle the values of the array.
Also allows edition in raw mode.
`argTypes: { odd: { control: 'object' }}` | +| **array** | `object` | Provides a JSON-based editor component to handle the array's values.
Also allows edition in raw mode.
`argTypes: { odd: { control: 'object' }}` | | | `file` | Provides a file input component that returns an array of URLs.
Can be further customized to accept specific file types.
`argTypes: { avatar: { control: { type: 'file', accept: '.png' } }}` | | **enum** | `radio` | Provides a set of radio buttons based on the available options.
`argTypes: { contact: { control: 'radio', options: ['email', 'phone', 'mail'] }}` | | | `inline-radio` | Provides a set of inlined radio buttons based on the available options.
`argTypes: { contact: { control: 'inline-radio', options: ['email', 'phone', 'mail'] }}` | @@ -512,117 +632,13 @@ It may also contain at most one of the following operators: If no operator is provided, that is equivalent to `{ truthy: true }`. - + ## Troubleshooting ### Controls are not automatically generated for my component -Out of the box, Storybook will try to infer the required argTypes and associated controls for your stories based on the component's definition and the initial value of the args. However, in some cases, this may not be enough, and you may need to provide additional information to Storybook. To solve this, you can opt-in to use [Compodoc](https://compodoc.app/), a documentation generator for Angular applications that can extract the metadata of your components and generate the required argTypes and controls for your stories. - -Run the following command to install the tooling. - - - - - - - -Update your `angular.json` file to include the following configuration to include it in the Storybook's inbuilt builder configuration. - - - - - - - - -Finally, update your `.storybook/preview.ts` file to include the following configuration to import the metadata generated by Compodoc and use it to generate the controls and argTypes for your stories. - - - - - - - - - - - - -## Troubleshooting - -### Controls are not automatically generated for my component - -Out of the box, Storybook will try to infer the required argTypes and associated controls for your stories based on the component's definition and the initial value of the args. However, in some cases, this may not be enough, and you may need to provide additional information to Storybook. To solve this, you can generate a [`custom-elements.json`](https://github.com/webcomponents/custom-elements-json) file with [`@custom-elements-manifest/analyzer`](https://github.com/open-wc/custom-elements-manifest) if you're using the `pre-v1.0.0` version of the elements file or [`@custom-elements-manifest/analyzer`](https://github.com/open-wc/custom-elements-manifest) for newer versions and configure it in your Storybook UI configuration file (i.e., `.storybook/preview.js|ts`) to enable it. - - - - - - - - - - - - -## Troubleshooting - -### Controls are not automatically generated for my component - -Out of the box, Storybook will try to infer the required argTypes and associated controls for your stories based on the metadata provided by the [`@storybook/ember-cli-storybook`](https://github.com/storybookjs/ember-cli-storybook) addon. However, in some cases, this may not be enough, and you may need to customize your project configuration to provide additional information to Storybook to generate the required argTypes and controls for your stories. - -Update your `ember-cli-build.js` configuration file to include the addon. - - - - - - - - -Restart your application to generate the metadata file (i.e., `storybook-docgen/index.json`) and update your `.storybook/preview.js` file to include it, which will be used to create the controls and argTypes for your stories. - - - - - - - - - - -Enabling this feature will generate a `storybook-docgen/index.json` automatically with each build. For more information on how the metadata is generated, refer to [documentation](https://github.com/storybookjs/storybook/tree/next/code/frameworks/ember) for the Ember framework. - - +If you're working with Angular, Ember, or Web Components, automatic argTypes and controls inference will not work out of the box and requires you to provide [additional configuration](#choosing-the-control-type) to allow Storybook to retrieve the necessary metadata and generate the needed argTypes and controls for your stories. However, if you need additional customization, you can always [define them manually](#fully-custom-args). @@ -650,13 +666,7 @@ Specifies which properties to exclude from the Controls addon panel. Any propert Type: `boolean` -Show the full documentation, including description and default value, for each property in the Controls addon panel. See [usage example](#show-full-documentation-for-each-property), above. - -#### `hideNoControlsWarning` - -Type: `boolean` - -Hide the warning that appears when no controls are defined for a story. See [usage example](#hide-nocontrols-warning), above. +Show the full documentation for each property in the Controls addon panel, including the description and default value. See [usage example](#show-full-documentation-for-each-property), above. #### `include` @@ -668,7 +678,7 @@ Specifies which properties to include in the Controls addon panel. Any propertie Type: `(string | { color: string; title?: string })[]` -Specify preset color swatches for the color picker control. Color value many be any valid CSS color. See [usage example](#specify-initial-preset-color-swatches), above. +Specify preset color swatches for the color picker control. The color value may be any valid CSS color. See [usage example](#specify-initial-preset-color-swatches), above. #### `sort` diff --git a/docs/snippets/angular/compodoc-install.pnpm.js.mdx b/docs/snippets/angular/compodoc-install.pnpm.js.mdx index 116346afd228..37c0310aa158 100644 --- a/docs/snippets/angular/compodoc-install.pnpm.js.mdx +++ b/docs/snippets/angular/compodoc-install.pnpm.js.mdx @@ -1,3 +1,3 @@ ```shell -pnpm add --save-dev @compodoc/compodo +pnpm add --save-dev @compodoc/compodoc ``` diff --git a/docs/snippets/common/main-config-typescript-check-options.ts.mdx b/docs/snippets/common/main-config-typescript-check-options.ts.mdx index 0581f7ee5ebf..90f5e7beeaa9 100644 --- a/docs/snippets/common/main-config-typescript-check-options.ts.mdx +++ b/docs/snippets/common/main-config-typescript-check-options.ts.mdx @@ -1,7 +1,7 @@ ```ts // .storybook/main.ts -// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite) +// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-webpack5) import type { StorybookConfig } from '@storybook/your-framework'; const config: StorybookConfig = { diff --git a/docs/snippets/common/main-config-typescript-check.ts.mdx b/docs/snippets/common/main-config-typescript-check.ts.mdx index 5f0149dfcb5e..7c687ffbef58 100644 --- a/docs/snippets/common/main-config-typescript-check.ts.mdx +++ b/docs/snippets/common/main-config-typescript-check.ts.mdx @@ -1,7 +1,7 @@ ```ts // .storybook/main.ts -// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite) +// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-webpack5) import type { StorybookConfig } from '@storybook/your-framework'; const config: StorybookConfig = { diff --git a/docs/snippets/common/storybook-main-extend-ts-config.ts.mdx b/docs/snippets/common/storybook-main-extend-ts-config.ts.mdx index a7fa7fd28444..7884f8a4724a 100644 --- a/docs/snippets/common/storybook-main-extend-ts-config.ts.mdx +++ b/docs/snippets/common/storybook-main-extend-ts-config.ts.mdx @@ -8,14 +8,9 @@ const config: StorybookConfig = { framework: '@storybook/your-framework', stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], typescript: { - reactDocgen: 'react-docgen-typescript', - reactDocgenTypescriptOptions: { - compilerOptions: { - allowSyntheticDefaultImports: false, - esModuleInterop: false, - }, - propFilter: () => true, - }, + check: false, + checkOptions: {}, + skipCompiler: false, }, }; diff --git a/docs/snippets/common/storybook-vite-builder-react-docgen.js.mdx b/docs/snippets/common/storybook-vite-builder-react-docgen.js.mdx index 99ef2c6a0372..84d035998c63 100644 --- a/docs/snippets/common/storybook-vite-builder-react-docgen.js.mdx +++ b/docs/snippets/common/storybook-vite-builder-react-docgen.js.mdx @@ -8,7 +8,9 @@ export default { builder: '@storybook/builder-vite', }, typescript: { - reactDocgen: 'react-docgen', // 👈 react-docgen configured here. + // Enables the `react-docgen-typescript` parser. + // See https://storybook.js.org/docs/api/main-config-typescript for more information about this option. + reactDocgen: 'react-docgen-typescript', }, }; ``` diff --git a/docs/snippets/common/main-config-typescript-react-docgen-typescript-options.ts.mdx b/docs/snippets/react/main-config-typescript-react-docgen-typescript-options.ts.mdx similarity index 95% rename from docs/snippets/common/main-config-typescript-react-docgen-typescript-options.ts.mdx rename to docs/snippets/react/main-config-typescript-react-docgen-typescript-options.ts.mdx index fc36649054e1..77319b608505 100644 --- a/docs/snippets/common/main-config-typescript-react-docgen-typescript-options.ts.mdx +++ b/docs/snippets/react/main-config-typescript-react-docgen-typescript-options.ts.mdx @@ -1,7 +1,7 @@ ```ts // .storybook/main.ts -// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite) +// Replace your-framework with the framework you are using (e.g., react-webpack5, react-vite) import type { StorybookConfig } from '@storybook/your-framework'; const config: StorybookConfig = { diff --git a/docs/snippets/common/main-config-typescript-react-docgen.ts.mdx b/docs/snippets/react/main-config-typescript-react-docgen.ts.mdx similarity index 83% rename from docs/snippets/common/main-config-typescript-react-docgen.ts.mdx rename to docs/snippets/react/main-config-typescript-react-docgen.ts.mdx index 6b908ac4000f..c96821c5a7ce 100644 --- a/docs/snippets/common/main-config-typescript-react-docgen.ts.mdx +++ b/docs/snippets/react/main-config-typescript-react-docgen.ts.mdx @@ -1,14 +1,14 @@ ```ts // .storybook/main.ts -// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite) +// Replace your-framework with the framework you are using (e.g., react-webpack5, react-vite) import type { StorybookConfig } from '@storybook/your-framework'; const config: StorybookConfig = { framework: '@storybook/your-framework', stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], typescript: { - reactDocgen: 'react-docgen-typescript', + reactDocgen: 'react-docgen', }, }; diff --git a/docs/snippets/react/storybook-main-extend-ts-config.ts.mdx b/docs/snippets/react/storybook-main-extend-ts-config.ts.mdx new file mode 100644 index 000000000000..abf80d6e62f2 --- /dev/null +++ b/docs/snippets/react/storybook-main-extend-ts-config.ts.mdx @@ -0,0 +1,20 @@ +```ts +// .storybook/main.ts + +// Replace your-framework with the framework you are using (e.g., react-webpack5, react-vite) +import type { StorybookConfig } from '@storybook/your-framework'; + +const config: StorybookConfig = { + framework: '@storybook/your-framework', + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], + typescript: { + check: false, + checkOptions: {}, + reactDocgen: 'react-docgen', + reactDocgenTypescriptOptions: {}, // Available only when reactDocgen is set to 'react-docgen-typescript' + skipCompiler: true, + }, +}; + +export default config; +``` diff --git a/docs/snippets/react/storybook-main-prop-filter.ts.mdx b/docs/snippets/react/storybook-main-prop-filter.ts.mdx new file mode 100644 index 000000000000..4dd6b9d649e5 --- /dev/null +++ b/docs/snippets/react/storybook-main-prop-filter.ts.mdx @@ -0,0 +1,25 @@ +```ts +// .storybook/main.ts + +// Replace your-framework with the framework you are using (e.g., react-webpack5, react-vite) +import type { StorybookConfig } from '@storybook/your-framework'; + +const config: StorybookConfig = { + framework: '@storybook/your-framework', + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], + typescript: { + reactDocgen: 'react-docgen-typescript', + reactDocgenTypescriptOptions: { + compilerOptions: { + allowSyntheticDefaultImports: false, + esModuleInterop: false, + }, + // Filter out third-party props from node_modules except @mui packages. + propFilter: (prop) => + prop.parent ? !/node_modules\/(?!@mui)/.test(prop.parent.fileName) : true, + }, + }, +}; + +export default config; +``` diff --git a/docs/snippets/react/storybook-main-react-docgen-typescript.ts.mdx b/docs/snippets/react/storybook-main-react-docgen-typescript.ts.mdx new file mode 100644 index 000000000000..8dc82534b82f --- /dev/null +++ b/docs/snippets/react/storybook-main-react-docgen-typescript.ts.mdx @@ -0,0 +1,19 @@ +```ts +// .storybook/main.ts + +// Replace your-framework with the framework you are using (e.g., react-webpack5, react-vite) +import type { StorybookConfig } from '@storybook/your-framework'; + +const config: StorybookConfig = { + framework: '@storybook/your-framework', + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], + typescript: { + reactDocgen: 'react-docgen-typescript', + // Provide your own options if necessary. + // See https://storybook.js.org/docs/configure/typescript for more information. + reactDocgenTypescriptOptions: {}, + }, +}; + +export default config; +```