diff --git a/docs/configure/frameworks-feature-support.md b/docs/configure/frameworks-feature-support.md index 8b1ae823ed3d..306ee9e94160 100644 --- a/docs/configure/frameworks-feature-support.md +++ b/docs/configure/frameworks-feature-support.md @@ -10,10 +10,108 @@ Below is a comprehensive table of what’s supported in which framework integrat Core frameworks have dedicated maintainers or contributors who are responsible for maintaining the integration. As such, you can use most Storybook features in these frameworks. - +| | React | Vue | Angular | Web Components | +| ----------------------------------------------------------------------------------------- | ----- | --- | ------- | -------------- | +| **Essentials** | | | | | +| [Actions](../essentials/actions.md) | ✅ | ✅ | ✅ | ✅ | +| [Backgrounds](../essentials/backgrounds.md) | ✅ | ✅ | ✅ | ✅ | +| [Docs](../writing-docs/index.md) | ✅ | ✅ | ✅ | ✅ | +| [Viewport](../essentials/viewport.md) | ✅ | ✅ | ✅ | ✅ | +| [Controls](../essentials/controls.md) | ✅ | ✅ | ✅ | ✅ | +| [Measure](../essentials/measure-and-outline.md#measure-addon) | ✅ | ✅ | ✅ | ✅ | +| [Outline](../essentials/measure-and-outline.md#outline-addon) | ✅ | ✅ | ✅ | ✅ | +| **Addons** | | | | | +| [A11y](../writing-tests/accessibility-testing.md) | ✅ | ✅ | ✅ | ✅ | +| [Interactions](../writing-tests/interaction-testing.md) | ✅ | ✅ | ✅ | ✅ | +| [Test runner](../writing-tests/test-runner.md) | ✅ | ✅ | ✅ | ✅ | +| [Test coverage](../writing-tests/test-coverage.md) | ✅ | ✅ | ✅ | ✅ | +| [CSS resources](https://github.com/storybookjs/addon-cssresources) | ✅ | ✅ | ✅ | ✅ | +| [Design assets](https://github.com/storybookjs/addon-design-assets) | ✅ | ✅ | ✅ | ✅ | +| [Events](https://github.com/storybookjs/addon-events) | ✅ | ✅ | ✅ | ✅ | +| [Google analytics](https://github.com/storybookjs/addon-google-analytics) | ✅ | ✅ | ✅ | ✅ | +| [GraphQL](https://github.com/storybookjs/addon-graphql) | ✅ | | ✅ | | +| [Jest](https://github.com/storybookjs/storybook/tree/next/code/addons/jest) | ✅ | ✅ | ✅ | ✅ | +| [Links](https://github.com/storybookjs/storybook/tree/next/code/addons/links) | ✅ | ✅ | ✅ | ✅ | +| [Queryparams](https://github.com/storybookjs/addon-queryparams) | ✅ | ✅ | ✅ | ✅ | +| [Storysource](https://github.com/storybookjs/storybook/tree/next/code/addons/storysource) | ✅ | ✅ | ✅ | ✅ | +| **Docs** | | | | | +| [CSF Stories](../api/csf.md) | ✅ | ✅ | ✅ | ✅ | +| [Autodocs](../writing-docs/autodocs.md) | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - ArgTypes](../api/doc-block-argtypes.md) | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Canvas](../api/doc-block-canvas.md) | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - ColorPalette](../api/doc-block-colorpalette.md) | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Controls](../api/doc-block-controls.md) | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Description](../api/doc-block-description.md) | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - IconGallery](../api/doc-block-icongallery.md) | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Markdown](../api/doc-block-markdown.md) | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Meta](../api/doc-block-meta.md) | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Primary](../api/doc-block-primary.md) | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Source](../api/doc-block-source.md) | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Story](../api/doc-block-story.md) | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Stories](../api/doc-block-stories.md) | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Subtitle](../api/doc-block-subtitle.md) | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Title](../api/doc-block-title.md) | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Typeset](../api/doc-block-typeset.md) | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Unstyled](../api/doc-block-unstyled.md) | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - UseOf](../api/doc-block-useof.md) | ✅ | ✅ | ✅ | ✅ | +| Inline stories | ✅ | ✅ | ✅ | ✅ | ## Community frameworks Community frameworks have fewer contributors which means they may not be as up to date as core frameworks. If you use one of these frameworks for your job, please consider contributing to its integration with Storybook. - +| | Ember | HTML | Svelte | Preact | Qwik | SolidJS | +| ----------------------------------------------------------------------------------------- | ----- | ---- | ------ | ------ | ---- | ------- | +| **Essentials** | | | | | | | +| [Actions](../essentials/actions.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Backgrounds](../essentials/backgrounds.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Docs](../writing-docs/index.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Viewport](../essentials/viewport.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Controls](../essentials/controls.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Measure](../essentials/measure-and-outline.md#measure-addon) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Outline](../essentials/measure-and-outline.md#outline-addon) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| **Addons** | | | | | | | +| [A11y](../writing-tests/accessibility-testing.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Interactions](../writing-tests/interaction-testing.md) | | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Test runner](../writing-tests/test-runner.md) | | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Test coverage](../writing-tests/test-coverage.md) | | ✅ | ✅ | ✅ | ✅ | ✅ | +| [CSS resources](https://github.com/storybookjs/addon-cssresources) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Design assets](https://github.com/storybookjs/addon-design-assets) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Events](https://github.com/storybookjs/addon-events) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Google analytics](https://github.com/storybookjs/addon-google-analytics) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [GraphQL](https://github.com/storybookjs/addon-graphql) | | | | | | | +| [Jest](https://github.com/storybookjs/storybook/tree/next/code/addons/jest) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Links](https://github.com/storybookjs/storybook/tree/next/code/addons/links) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Queryparams](https://github.com/storybookjs/addon-queryparams) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Storysource](https://github.com/storybookjs/storybook/tree/next/code/addons/storysource) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| **Docs** | | | | | | | +| [CSF Stories](../api/csf.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Autodocs](../writing-docs/autodocs.md) | | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - ArgTypes](../api/doc-block-argtypes.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Canvas](../api/doc-block-canvas.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - ColorPalette](../api/doc-block-colorpalette.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Controls](../api/doc-block-controls.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Description](../api/doc-block-description.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - IconGallery](../api/doc-block-icongallery.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Markdown](../api/doc-block-markdown.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Meta](../api/doc-block-meta.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Primary](../api/doc-block-primary.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Source](../api/doc-block-source.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Story](../api/doc-block-story.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Stories](../api/doc-block-stories.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Subtitle](../api/doc-block-subtitle.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Title](../api/doc-block-title.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Typeset](../api/doc-block-typeset.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - Unstyled](../api/doc-block-unstyled.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| [Doc Blocks - UseOf](../api/doc-block-useof.md) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| Inline stories | | ✅ | ✅ | | | | + +## Deprecated + +To align the Storybook ecosystem with the current state of frontend development, the following features and addons are now deprecated, no longer maintained, and will be removed in future versions of Storybook + +| Feature | Status | +| -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Knobs](https://github.com/storybookjs/addon-knobs) | The Knobs addon was officially deprecated with the release of Storybook 6.3 and is no longer actively maintained. We recommend using the [controls](../essentials/controls.md) instead. | +| [Storyshots](../writing-tests/snapshot-testing.md) | The Storyshots addon was officially deprecated with the release of Storybook 7.6 and is no longer actively maintained. See the [migration guide](../writing-tests/storyshots-migration-guide.md) for the available alternatives. | +| [`StoriesOf`](https://github.com/storybookjs/storybook/blob/next/code/lib/preview-api/docs/storiesOf.md) | The `storiesOf` API was officially deprecated with the release of Storybook 7.5 and is no longer actively maintained. We recommend using the [CSF API](../api/csf.md) instead for writing stories.
See the [migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#storystorev6-and-storiesof-is-deprecated) for more information. | diff --git a/docs/essentials/auto-generated-controls/angular.mdx b/docs/essentials/auto-generated-controls/angular.mdx deleted file mode 100644 index 22417afdbb66..000000000000 --- a/docs/essentials/auto-generated-controls/angular.mdx +++ /dev/null @@ -1,68 +0,0 @@ -To use auto-detected controls with Angular, you must fill in the `component` field in your story metadata: - -```ts -import { Button } from './button.component'; - -export default { - component: Button, -}; -``` - -Storybook uses this to auto-generate the `ArgTypes` for your component using [Compodoc](https://compodoc.app/). It supports `inputs`, `outputs`, `properties`, `methods`, `view/content child/children` as first class prop types. - -## Automatic Compodoc setup - -During `sb init`, you will be asked, whether you want to setup Compodoc for your project. Just answer the question with Yes. Compodoc is then ready to use! - -## Manual Compodoc setup - -You'll need to register Compodoc's `documentation.json` file in `.storybook/preview.ts`: - -```js -import { setCompodocJson } from '@storybook/addon-docs/angular'; -import docJson from '../documentation.json'; - -setCompodocJson(docJson); -``` - -Finally, to set up compodoc, you'll first need to install Compodoc: - -```sh -yarn add -D @compodoc/compodoc -``` - -Then you'll need to configure Compodoc to generate a `documentation.json` file. Adding the following snippet to your `projects..architect.` in the `angular.json` creates a metadata file `./documentation.json` each time you run storybook: - -```jsonc -// angular.json -{ - "projects": { - "your-project": { - "architect": { - "storybook": { - ..., - "compodoc": true, - "compodocArgs": [ - "-e", - "json", - "-d", - "." // the root folder of your project - ], - }, - "build-storybook": { - ..., - "compodoc": true, - "compodocArgs": [ - "-e", - "json", - "-d", - "." // the root folder of your project - ], - } - } - } - } -} -``` - -Unfortunately, it's not currently possible to update this dynamically as you edit your components, but [there's an open issue](https://github.com/storybookjs/storybook/issues/8672) to support this with improvements to Compodoc. diff --git a/docs/essentials/auto-generated-controls/ember.mdx b/docs/essentials/auto-generated-controls/ember.mdx deleted file mode 100644 index 1696095183a9..000000000000 --- a/docs/essentials/auto-generated-controls/ember.mdx +++ /dev/null @@ -1,29 +0,0 @@ -Storybook for Ember relies on [@storybook/ember-cli-storybook addon](https://github.com/storybookjs/ember-cli-storybook), to extract documentation comments from your component source files. If you're using Storybook with Ember, you should already have this addon installed, and you will just need to enable it by adding the following config block in your `ember-cli-build.js` file: - -```js -let app = new EmberApp(defaults, { - '@storybook/ember-cli-storybook': { - enableAddonDocsIntegration: true, - }, -}); -``` - -Now, running the ember-cli server will generate a JSON documentation file at `/dist/storybook-docgen/index.json`. Since generation of this file is tied into the ember-cli build, it will get regenerated every time component files are saved. For details on documenting your components, check out the examples in the addon that powers the generation [ember-cli-addon-docs-yuidoc](https://github.com/ember-learn/ember-cli-addon-docs-yuidoc#documenting-components). - -Storybook uses this file to auto-generate the `ArgTypes` for your component based on docgen information created by [ember-cli-addon-docs-yuidoc](https://github.com/ember-learn/ember-cli-addon-docs-yuidoc#documenting-components). - -You'll need to register that in `.storybook/preview.js`: - -```js -import { setJSONDoc } from '@storybook/addon-docs/ember'; -import docJson from '../dist/storybook-docgen/index.json'; -setJSONDoc(docJson); -``` - -Finally, to use auto-detected controls with Ember, you must fill in the `component` field in your story metadata: - -```ts -export default { - component: 'button', // name of your button component from docgen-json file (index.js) -}; -``` diff --git a/docs/essentials/auto-generated-controls/fallback.mdx b/docs/essentials/auto-generated-controls/fallback.mdx deleted file mode 100644 index 9842a53b859d..000000000000 --- a/docs/essentials/auto-generated-controls/fallback.mdx +++ /dev/null @@ -1,3 +0,0 @@ -Controls argument autodetection doesn't currently work with your framework. - -To use Controls, you'll need to [define the `ArgTypes` manually](#fully-custom-args) diff --git a/docs/essentials/auto-generated-controls/react.mdx b/docs/essentials/auto-generated-controls/react.mdx deleted file mode 100644 index 29bb07ede5c1..000000000000 --- a/docs/essentials/auto-generated-controls/react.mdx +++ /dev/null @@ -1,14 +0,0 @@ -To use auto-detected controls with React, you must fill in the `component` field in your story metadata: - -```js -// Button.stories.js|jsx|mjs|ts|tsx - -import { Button } from './Button'; - -export default { - component: Button, -}; -``` - - -Storybook uses this to auto-generate the `ArgTypes` for your component based on either `PropTypes` (using [`react-docgen`](https://github.com/reactjs/react-docgen)) or `TypeScript` types (using [`react-docgen-typescript`](https://github.com/styleguidist/react-docgen-typescript)). diff --git a/docs/essentials/auto-generated-controls/vue.mdx b/docs/essentials/auto-generated-controls/vue.mdx deleted file mode 100644 index 740ea7bec825..000000000000 --- a/docs/essentials/auto-generated-controls/vue.mdx +++ /dev/null @@ -1,11 +0,0 @@ -To use auto-detected controls with Vue, you must fill in the `component` field in your story metadata: - -```js -import { Button } from './Button.vue'; - -export default { - component: Button, -}; -``` - -Storybook uses this to auto-generate the `ArgTypes` for your component using [`vue-docgen-api`](https://github.com/vue-styleguidist/vue-styleguidist/tree/dev/packages/vue-docgen-api). It supports `props`, `events`, and `slots` as first class prop types. diff --git a/docs/essentials/auto-generated-controls/web-components.mdx b/docs/essentials/auto-generated-controls/web-components.mdx deleted file mode 100644 index 473b67f07b21..000000000000 --- a/docs/essentials/auto-generated-controls/web-components.mdx +++ /dev/null @@ -1,20 +0,0 @@ -To use auto-detected controls with Web components, you must fill in the `component` field in your story metadata: - -```js -export default { - component: 'button', -}; -``` - -Storybook uses this to auto-generate the `ArgTypes` for your component using your [custom-elements.json](https://github.com/webcomponents/custom-elements-json) file. - -You'll need to register that in `.storybook/preview.js`: - -```js -import { setCustomElementsManifest } from '@storybook/web-components'; -import customElements from '../custom-elements.json'; - -setCustomElementsManifest(customElements); -``` - -You can generate a `custom-elements.json` using [@custom-elements-manifest/analyzer](https://github.com/open-wc/custom-elements-manifest). If you're using the pre-v1.0.0 version of `custom-elements.json` you can use either [web-component-analyzer](https://github.com/runem/web-component-analyzer). diff --git a/docs/essentials/controls.md b/docs/essentials/controls.md index efff7222f5bd..5d86420c4ab0 100644 --- a/docs/essentials/controls.md +++ b/docs/essentials/controls.md @@ -29,23 +29,83 @@ If you have stories in the older pre-Storybook 6 style, check the [args & contro ## Choosing the control type -By default, Storybook will choose a control for each arg based on the initial value of the arg. It works well with certain types of args, such as boolean values or free-text strings, but in other cases, you want a more restricted control. + + +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 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 [`vue-docgen-api`](https://github.com/vue-styleguidist/vue-styleguidist/tree/dev/packages/vue-docgen-api), including first-class support for Vue's `props`, `events`, and `slots`. - + + + + +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. + + + + + + + +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). + + + + + For instance, suppose you have a `variant` arg on your story that should be `primary` or `secondary`: @@ -70,7 +130,7 @@ By default, Storybook will render a free text input for the `variant` arg: It works as long as you type a valid string into the auto-generated text control. Still, it's not the best UI for our scenario, given that the component only accepts `primary` or `secondary` as variants. Let’s replace it with Storybook’s radio component. -We can specify which controls get used by declaring a custom [argType](../api/arg-types.md) for the `variant` property. ArgTypes encode basic metadata for args, such as name, description, defaultValue for an arg. These get automatically filled in by Storybook Docs. +We can specify which controls get used by declaring a custom [argType](../api/arg-types.md) for the `variant` property. ArgTypes encode basic metadata for args, such as name, description, and defaultValue for an arg. These get automatically filled in by Storybook Docs. `ArgTypes` can also contain arbitrary annotations, which the user can override. Since `variant` is a property of the component, let's put that annotation on the default export. @@ -91,7 +151,7 @@ We can specify which controls get used by declaring a custom [argType](../api/ar -ArgTypes are a powerful feature that can be used to customize the controls for your stories. See the documentation about [customizing controls](#annotation) with `argTypes` annotation for more information. +ArgTypes are a powerful feature that can be used to customize the controls for your stories. For more information, see the documentation about [customizing controls](#annotation) with `argTypes` annotation. @@ -101,14 +161,14 @@ This replaces the input with a radio group for a more intuitive experience. ## Custom control type matchers -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`: +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 | | :-------: | :--------------------------------------: | :-------------------------------------------------------: | | **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 | -If you haven't used the CLI to setup the configuration, or if you want to define your own patterns, use the `matchers` property in the `controls` parameter: +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: @@ -121,13 +181,13 @@ If you haven't used the CLI to setup the configuration, or if you want to define - + ## Fully custom args -Until now, we only used auto-generated controls based on the component we're writing stories for. If we are writing [complex stories](../writing-stories/stories-for-multiple-components.md), we may want to add controls for args that aren’t part of the component. For example, here's how you could use a `footer` arg to populate a child component: +Until now, we only used auto-generated controls based on the component for which we're writing stories. If we are writing [complex stories](../writing-stories/stories-for-multiple-components.md), we may want to add controls for args that aren’t part of the component. For example, here's how you could use a `footer` arg to populate a child component: @@ -189,7 +249,7 @@ One way to deal with this is to use primitive values (e.g., strings) as arg valu -Unless you need the flexibility of a function, an easier way to map primitives to complex values before rendering is to define a `mapping`, additionally, you can specify `control.labels` to configure custom labels for your checkbox, radio, or select input. +Unless you need the flexibility of a function, an easier way to map primitives to complex values before rendering is to define a `mapping`; additionally, you can specify `control.labels` to configure custom labels for your checkbox, radio, or select input. @@ -267,9 +327,9 @@ Numeric data types will default to a `number` control unless additional configur Controls supports the following configuration [parameters](../writing-stories/parameters.md), either globally or on a per-story basis: -## Show full documentation for each property +#### Show full documentation for each property -Since Controls is built on the same engine as Storybook Docs, it can also show property documentation alongside your controls using the expanded parameter (defaults to false). This means you embed a complete [`Controls`](../api/doc-block-controls.md) doc block in the controls panel. The description and default value rendering can be [customized](#fully-custom-args) in the same way as the doc block. +Since Controls is built on the same engine as Storybook Docs, it can also show property documentation alongside your controls using the expanded parameter (defaults to false). This means you embed a complete [`Controls`](../api/doc-block-controls.md) doc block in the controls panel. The description and default value rendering can be [customized](#fully-custom-args) like the doc block. To enable expanded mode globally, add the following to [`.storybook/preview.js`](../configure/index.md#configure-story-rendering): @@ -284,11 +344,11 @@ To enable expanded mode globally, add the following to [`.storybook/preview.js`] -And here's what the resulting UI looks like: +Here's what the resulting UI looks like: ![Controls addon expanded](./addon-controls-expanded.png) -### Specify initial preset color swatches +#### Specify initial preset color swatches For `color` controls, you can specify an array of `presetColors`, either on the `control` in `argTypes`, or as a parameter under the `controls` namespace: @@ -305,11 +365,75 @@ For `color` controls, you can specify an array of `presetColors`, either on the Color presets can be defined as an object with `color` and `title` or a simple CSS color string. These will then be available as swatches in the color picker. When you hover over the color swatch, you'll be able to see its title. It will default to the nearest CSS color name if none is specified. +#### Filtering controls + +In specific cases, you may be required to display only a limited number of controls in the controls panel or all except a particular set. + +To make this possible, you can use optional `include` and `exclude` configuration fields in the `controls` parameter, which you can define as an array of strings or a regular expression. + +Consider the following story snippets: + + + + + + + +#### Sorting controls + +By default, controls are unsorted and use whatever order the args data is processed in (`none`). Additionally, you can sort them alphabetically by the arg's name (`alpha`) or with the required args first (`requiredFirst`). + +Consider the following snippet to force required args first: + + + + + + + +#### Hide NoControls warning + +If you don't plan to handle the control args inside your story, you can remove the warning with: + + + + + + + ### Disable controls for specific properties Aside from the features already documented here, Controls can also be disabled for individual properties. -Suppose you want to disable Controls for a property called `foo` in a component's story. The following example illustrates how: +Suppose you want to turn off Controls for a property called `foo` in a component's story. The following example illustrates how: @@ -334,7 +458,7 @@ Resulting in the following change in Storybook UI: /> -The previous example also removed the prop documentation from the table. In some cases, this is fine. However, sometimes you might want to render the prop documentation, but without a control. The following example illustrates how: +The previous example also removed the prop documentation from the table. In some cases, this is fine. However, sometimes you might want to render the prop documentation without a control. The following example illustrates how: @@ -352,7 +476,7 @@ The previous example also removed the prop documentation from the table. In some -💡 As with other Storybook properties, such as [decorators](../writing-stories/decorators.md), you can apply the same pattern at a story level for more granular cases. +As with other Storybook properties, such as [decorators](../writing-stories/decorators.md), you can apply the same pattern at a story level for more granular cases. @@ -360,7 +484,7 @@ The previous example also removed the prop documentation from the table. In some In some cases, it's useful to be able to conditionally exclude a control based on the value of another control. Controls supports basic versions of these use cases with the `if`, which can take a simple query object to determine whether to include the control. -Consider a collection of "advanced" settings that are only visible when the user toggles an "advanced" toggle. +Consider a collection of "advanced" settings only visible when the user toggles an "advanced" toggle. @@ -410,66 +534,116 @@ It may also contain at most one of the following operators: If no operator is provided, that is equivalent to `{ truthy: true }`. -## Hide NoControls warning + + +## Troubleshooting + +### Controls are not automatically generated for my component -If you don't plan to handle the control args inside your Story, you can remove the warning with: +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. -## Filtering controls +Update your `angular.json` file to include the following configuration to include it in the Storybook's inbuilt builder configuration. -In specific cases, you may require to display only a limited number of controls in the controls panel, or all of them except a particular set. + -To make this possible, you can use optional `include` and `exclude` configuration fields in the `controls` parameter, which you can define as an array of strings, or as a regular expression. + -Consider the following story snippets: + + + +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. + -## Sorting controls + -By default, controls are unsorted and use whatever order the args data is processed in (`none`). Additionally, you can sort them alphabetically by the arg's name (`alpha`) or with the required args first (`requiredFirst`). + -Consider the following snippet to force required args first: +## 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. + + + + diff --git a/docs/get-started/install.md b/docs/get-started/install.md index 977a1e122c03..1ce934aab296 100644 --- a/docs/get-started/install.md +++ b/docs/get-started/install.md @@ -57,6 +57,12 @@ Storybook comes with a built-in development server featuring everything you need + + +Storybook collects completely anonymous data to help us improve user experience. Participation is optional, and you may [opt-out](../configure/telemetry.md#how-to-opt-out) if you'd not like to share any information. + + + ![Storybook welcome screen](./example-welcome.png) There are some noteworthy items here: @@ -66,36 +72,235 @@ There are some noteworthy items here: - A few example stories to get you started.
-

Troubleshooting

 +

Troubleshooting

 + +#### Run Storybook with other package managers -Below are some of the most common installation issues and instructions on how to solve them. +The Storybook CLI includes support for the industry's popular package managers (e.g., [Yarn](https://yarnpkg.com/), [npm](https://www.npmjs.com/), and [pnpm](https://pnpm.io/)) automatically detecting the one you are using when you initialize Storybook. However, if you want to use a specific package manager as the default, add the `--package-manager` flag to the installation command. For example: - - +#### The CLI doesn't detect my framework + +If you're working with a custom environment set up or need set up Storybook manually, you can use the `--type` flag to specify the framework you need to use. Listed below are the supported frameworks and examples of how to use them: + +| Framework | Type | +| -------------- | ---------------- | +| Angular | `angular` | +| Ember | `ember` | +| HTML | `html` | +| Next.js | `nextjs` | +| Preact | `preact` | +| Qwik | `qwik` | +| React | `react` | +| Server | `server` | +| Solid | `solid` | +| Svelte | `svelte` | +| Vue 2 | `vue` | +| Vue 3 | `vue3` | +| Web Components | `web-components` | -Storybook collects completely anonymous data to help us improve user experience. Participation is optional, and you may [opt-out](../configure/telemetry.md#how-to-opt-out) if you'd not like to share any information. + + + + + + +#### Run Storybook with Webpack 4 + +If you previously installed Storybook in a project that uses Webpack 4, it will no longer work. This is because Storybook now uses Webpack 5 by default. To solve this issue, we recommend you upgrade your project to Webpack 5 and then run the following command to migrate your project to the latest version of Storybook: + + + + + + + + + +#### Storybook doesn't work with my Angular project using the Angular CLI + +Out of the box, adding Storybook to an Angular project using the Angular CLI requires you to run the installation command from the root of the project or, if you're working with a monorepo environment, from the directory where the Angular configuration file (i.e., `angular.json`) is located as it will be used to set up the builder configuration necessary to run Storybook. However, if you need, you can extend the builder configuration to customize Storybook's behavior. Listed below are the supported options: + +| Configuration element | Description | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `"browserTarget"` | Build target to be served using the following format.
`"example-project:builder:config"` | +| `"tsConfig"` | Location of the TypeScript configuration file, relative to the current workspace.
`"tsConfig": "./tsconfig.json"`. | +| `"port"` | Port used by Storybook.
`"port": 6006` | +| `"host"` | Set up a custom host for Storybook.
`"host": "http://my-custom-host"` | +| `"configDir"` | Storybook configuration directory location.
`"configDir": ".storybook"` | +| `"https"` | Starts Storybook with HTTPS enabled.
`"https": true`
Requires custom certificate information. | +| `"sslCa"` | Provides an SSL certificate authority.
`"sslCa": "your-custom-certificate-authority"`
Optional usage with `"https"` | +| `"sslCert"` | Provides an SSL certificate.
`"sslCert": "your-custom-certificate"`
Required for `https` | +| `"sslKey"` | Provides an SSL key to serve Storybook.
`"sslKey": "your-ssl-key"` | +| `"smokeTest"` | Exit Storybook after successful start.
`"smokeTest": true` | +| `"ci"` | Starts Storybook in CI mode (skips interactive prompts and will not open browser window).
`"ci": true` | +| `"quiet"` | Filters Storybook verbose build output.
`"quiet": true` | +| `"docs"` | Starts Storybook in [documentation mode](../writing-docs/build-documentation.md#preview-storybooks-documentation).
`"docs": true` | +| `"styles"` | Provide the location of the [application's styles](../configure/styling-and-css.md#importing-css-files) to be used with Storybook.
`"styles": ["src/styles.css", "src/styles.scss"]`
| +| `"stylePreprocessorOptions"` | Provides further customization for style preprocessors resolved to the workspace root.
`"stylePreprocessorOptions": { "includePaths": ["src/styles"] }` | + + + + + +#### The CLI doesn't support my Ember version + +The Ember framework relies on an auxiliary package named [`@storybook/ember-cli-storybook`](https://www.npmjs.com/package/@storybook/ember-cli-storybook) to help you set up Storybook in your project. During the installation process you might run into the following warning message in your terminal: + +```shell +The ember generate entity-name command requires an entity name to be specified. +For more details, use ember help. +``` + +It may be the case that you're using an outdated version of the package and you need to update it to the latest version to solve this issue. + + + + + +#### Writing native Svelte stories + +Storybook provides a Svelte addon maintained by the community, enabling you to write stories for your Svelte components using the template syntax. You'll need to take some additional steps to enable this feature. + +Run the following command to install the addon. + + + + + + + +Update your Storybook configuration file (i.e., `.storybook/main.js|ts`) to include it. + + + + + + + + + +The community actively maintains the Svelte CSF addon but still lacks some features currently available in the official Storybook Svelte framework support. For more information, see [addon's documentation](https://github.com/storybookjs/addon-svelte-csf). -If all else fails, try asking for [help](https://storybook.js.org/community#support) + + +### The installation process seems flaky and keeps failing + +If you're still running into some issues during the installation process, we encourage you to check out the following resources: + + + +- [Storybook's Angular README](https://github.com/storybookjs/storybook/tree/next/code/frameworks/angular) for more information on how to set up Storybook in your Angular project. +- [Storybook's help documentation](https://storybook.js.org/community#support) to contact the community and ask for help. + + + + + +- [Storybook's Ember README](https://github.com/storybookjs/storybook/tree/next/code/frameworks/ember) for more information on how to set up Storybook in your Ember project. +- [Storybook's help documentation](https://storybook.js.org/community#support) to contact the community and ask for help. + + + + + +- [Storybook's HTML Webpack README](https://github.com/storybookjs/storybook/tree/next/code/frameworks/html-webpack5) for more information on how to set up Storybook in your HTML project with Webpack 5. +- [Storybook's HTML Vite README](https://github.com/storybookjs/storybook/tree/next/code/frameworks/html-vite) for more information on how to set up Storybook in your HTML project with Vite. +- [Storybook's help documentation](https://storybook.js.org/community#support) to contact the community and ask for help. + + + + + +- [Storybook's Preact Webpack README](https://github.com/storybookjs/storybook/tree/next/code/frameworks/preact-webpack5) for more information on how to set up Storybook in your Preact project with Webpack 5. +- [Storybook's Preact Vite README](https://github.com/storybookjs/storybook/tree/next/code/frameworks/preact-vite) for more information on how to set up Storybook in your Preact project with Vite. +- [Storybook's help documentation](https://storybook.js.org/community#support) to contact the community and ask for help. + + + + + +- [Storybook's Qwik README](https://github.com/literalpie/storybook-framework-qwik) for more information on how to set up Storybook in your Qwik project. +- [Storybook's help documentation](https://storybook.js.org/community#support) to contact the community and ask for help. + + + + + +- [Storybook's React Webpack README](https://github.com/storybookjs/storybook/tree/next/code/frameworks/react-webpack5) for more information on how to set up Storybook in your React project with Webpack 5. +- [Storybook's React Vite README](https://github.com/storybookjs/storybook/tree/next/code/frameworks/react-vite) for more information on how to set up Storybook in your React project with Vite. +- [Storybook's help documentation](https://storybook.js.org/community#support) to contact the community and ask for help. + + + + + +- [Storybook's SolidJS README](https://github.com/storybookjs/solidjs) for more information on how to set up Storybook in your SolidJS project. +- [Storybook's help documentation](https://storybook.js.org/community#support) to contact the community and ask for help. + + + + + +- [Storybook's SvelteKit README](https://github.com/storybookjs/storybook/tree/next/code/frameworks/sveltekit) for more information on how to set up Storybook in your SvelteKit project. +- [Storybook's Svelte Webpack README](https://github.com/storybookjs/storybook/tree/next/code/frameworks/svelte-webpack5) for more information on how to set up Storybook in your Svelte project with Webpack 5. +- [Storybook's help documentation](https://storybook.js.org/community#support) to contact the community and ask for help. + + + + + +- [Storybook's Vue 2 Webpack README](https://github.com/storybookjs/storybook/tree/main/code/frameworks/vue-webpack5) for more information on how to set up Storybook in your Vue 2 project with Webpack 5. +- [Storybook's Vue 2 Vite README](https://github.com/storybookjs/storybook/tree/main/code/frameworks/vue-vite) for more information on how to set up Storybook in your Vue 2 project with Vite. +- [Storybook's Vue 3 Webpack README](https://github.com/storybookjs/storybook/tree/next/code/frameworks/vue3-webpack5) for more information on how to set up Storybook in your Vue 3 project with Webpack 5. +- [Storybook's Vue 3 Vite README](https://github.com/storybookjs/storybook/tree/next/code/frameworks/vue3-vite) for more information on how to set up Storybook in your Vue 3 project with Vite. +- [Storybook's help documentation](https://storybook.js.org/community#support) to contact the community and ask for help. + + + + + +- [Storybook's Web Components Webpack README](https://github.com/storybookjs/storybook/tree/next/code/frameworks/web-components-webpack55) for more information on how to set up Storybook in your Web Components project with Webpack 5. +- [Storybook's Web Components Vite README](https://github.com/storybookjs/storybook/tree/next/code/frameworks/web-components-vite) for more information on how to set up Storybook in your Web Components project with Vite. +- [Storybook's help documentation](https://storybook.js.org/community#support) to contact the community and ask for help. + +
diff --git a/docs/get-started/installation-command-section/solid.mdx b/docs/get-started/installation-command-section/solid.mdx deleted file mode 100644 index 41e5c040cc9d..000000000000 --- a/docs/get-started/installation-command-section/solid.mdx +++ /dev/null @@ -1,15 +0,0 @@ -Use the Storybook CLI to install it in a single command. Run this inside your _existing project’s_ root directory: - -- With npm: - -```shell -npx storybook init -``` - -- With pnpm: - -```shell -pnpm dlx storybook init -``` - -If you run into issues with the installation, check the [Troubleshooting section](#troubleshooting) below for guidance on how to solve it. diff --git a/docs/get-started/installation-problems/angular.mdx b/docs/get-started/installation-problems/angular.mdx deleted file mode 100644 index 96b96b440a7b..000000000000 --- a/docs/get-started/installation-problems/angular.mdx +++ /dev/null @@ -1,45 +0,0 @@ -- Add the `--type angular` flag to the installation command to set up Storybook manually: - - ```shell - npx storybook@latest init --type angular - ``` - -- Storybook's CLI provides support for [Yarn](https://yarnpkg.com/), [npm](https://www.npmjs.com/), and [pnpm](https://pnpm.io/) package managers. If you have Yarn installed in your environment but prefer to use another as your default package manager add the `--package-manager` flag to your installation command. For example: - - ```shell - npx storybook@latest init --package-manager=npm - ``` - -- Storybook supports Webpack 5 out of the box. If you're upgrading from a previous version, run the following command to enable it: - - ```shell - npx storybook@latest automigrate - ``` - - Check the [Migration Guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#automigrate) for more information on how to set up Webpack 5. - -- If you're using the custom Storybook builder, Storybook will not automatically open a browser window or tab. It's is a known issue that we plan to fix in future releases. - -- When adding Storybook to your Angular project, check if you're running the install command from the root directory. Or in a monorepo environment inside the directory where the `angular.json` file is located. - -- If you need further customization to the Storybook builder configuration, you can use the following table as a reference: - -| Configuration element | Description | -| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `"browserTarget"` | Build target to be served using the following format.
`"example-project:builder:config"` | -| `"tsConfig"` | Location of the TypeScript configuration file, relative to the current workspace.
`"tsConfig": "./tsconfig.json"`. | -| `"port"` | Port used by Storybook.
`"port": 6006` | -| `"host"` | Set up a custom host for Storybook.
`"host": "http://my-custom-host"` | -| `"configDir"` | Storybook configuration directory location.
`"configDir": ".storybook"` | -| `"https"` | Starts Storybook with HTTPS enabled.
`"https": true`
Requires custom certificate information. | -| `"sslCa"` | Provides an SSL certificate authority.
`"sslCa": "your-custom-certificate-authority"`
Optional usage with `"https"` | -| `"sslCert"` | Provides an SSL certificate.
`"sslCert": "your-custom-certificate"`
Required for `https` | -| `"sslKey"` | Provides an SSL key to serve Storybook.
`"sslKey": "your-ssl-key"` | -| `"smokeTest"` | Exit Storybook after successful start.
`"smokeTest": true` | -| `"ci"` | Starts Storybook in CI mode (skips interactive prompts and will not open browser window).
`"ci": true` | -| `"quiet"` | Filters Storybook verbose build output.
`"quiet": true` | -| `"docs"` | Starts Storybook in [documentation mode](../writing-docs/build-documentation.md#preview-storybooks-documentation).
`"docs": true` | -| `"styles"` | Provide the location of the [application's styles](../configure/styling-and-css.md#importing-css-files) to be used with Storybook.
`"styles": ["src/styles.css", "src/styles.scss"]`
| -| `"stylePreprocessorOptions"` | Provides further customization for style preprocessors resolved to the workspace root.
`"stylePreprocessorOptions": { "includePaths": ["src/styles"] }` | - -- For other installation issues, check the [Angular README](https://github.com/storybookjs/storybook/tree/next/code/frameworks/angular) for additional instructions. diff --git a/docs/get-started/installation-problems/ember.mdx b/docs/get-started/installation-problems/ember.mdx deleted file mode 100644 index a396c27891bd..000000000000 --- a/docs/get-started/installation-problems/ember.mdx +++ /dev/null @@ -1,23 +0,0 @@ -- Add the `--type ember` flag to the installation command to set up Storybook manually: - - ```shell - npx storybook@latest init --type ember - ``` - -- During the install process, if you get the following warning message: - - ```shell - The ember generate entity-name command requires an entity name to be specified. - - For more details, use ember help. - ``` - -Update the [`@storybook/ember-cli-storybook`](https://www.npmjs.com/package/@storybook/ember-cli-storybook) package to the latest version to fix it. - -- Storybook's CLI provides support for [Yarn](https://yarnpkg.com/), [npm](https://www.npmjs.com/), and [pnpm](https://pnpm.io/) package managers. If you have Yarn installed in your environment but prefer to use another as your default package manager add the `--package-manager` flag to your installation command. For example: - - ```shell - npx storybook@latest init --package-manager=npm - ``` - -- For other installation issues, check the [Ember README](https://github.com/storybookjs/storybook/tree/next/code/frameworks/ember) for additional instructions. diff --git a/docs/get-started/installation-problems/html.mdx b/docs/get-started/installation-problems/html.mdx deleted file mode 100644 index f43b72620b10..000000000000 --- a/docs/get-started/installation-problems/html.mdx +++ /dev/null @@ -1,9 +0,0 @@ -- Add the `--type html` flag to the installation command to set up Storybook manually: - - ```shell -npx storybook@latest init --type html - ``` - -- For other installation issues, check the React README files for additional instructions: - - [HTML with Webpack]( https://github.com/storybookjs/storybook/tree/next/code/frameworks/html-webpack5) - - [HTML with Vite](https://github.com/storybookjs/storybook/tree/next/code/frameworks/html-vite) diff --git a/docs/get-started/installation-problems/preact.mdx b/docs/get-started/installation-problems/preact.mdx deleted file mode 100644 index 24837b2c1ebd..000000000000 --- a/docs/get-started/installation-problems/preact.mdx +++ /dev/null @@ -1,13 +0,0 @@ -- Add the `--type preact` flag to the installation command to set up Storybook manually: - - ```shell - npx storybook@latest init --type preact - ``` - -- Storybook's CLI provides support for [Yarn](https://yarnpkg.com/), [npm](https://www.npmjs.com/), and [pnpm](https://pnpm.io/) package managers. If you have Yarn installed in your environment but prefer to use another as your default package manager add the `--package-manager` flag to your installation command. For example: - - ```shell - npx storybook@latest init --package-manager=npm - ``` - -- For other installation issues, check the [Preact README](https://github.com/storybookjs/storybook/tree/next/code/frameworks/preact-webpack5) for additional instructions. diff --git a/docs/get-started/installation-problems/qwik.mdx b/docs/get-started/installation-problems/qwik.mdx deleted file mode 100644 index c6bd50a043b4..000000000000 --- a/docs/get-started/installation-problems/qwik.mdx +++ /dev/null @@ -1,11 +0,0 @@ -- Add the `--type qwik` flag to the installation command to set up Storybook manually: - - ```shell - npx storybook@latest init --type qwik - ``` - -- Storybook's CLI provides support for [Yarn](https://yarnpkg.com/), [npm](https://www.npmjs.com/), and [pnpm](https://pnpm.io/) package managers. If you have Yarn installed in your environment but prefer to use another as your default package manager add the `--package-manager` flag to your installation command. For example: - - ```shell - npx storybook@latest init --package-manager=npm - ``` diff --git a/docs/get-started/installation-problems/react.mdx b/docs/get-started/installation-problems/react.mdx deleted file mode 100644 index 30b4643208c5..000000000000 --- a/docs/get-started/installation-problems/react.mdx +++ /dev/null @@ -1,23 +0,0 @@ -- Add the `--type react` flag to the installation command to set up Storybook manually: - - ```shell - npx storybook@latest init --type react - ``` - -- Storybook's CLI provides support for [Yarn](https://yarnpkg.com/), [npm](https://www.npmjs.com/), and [pnpm](https://pnpm.io/) package managers. If you have Yarn installed in your environment but prefer to use another as your default package manager add the `--package-manager` flag to your installation command. For example: - - ```shell - npx storybook@latest init --package-manager=npm - ``` - -- Storybook supports Webpack 5 out of the box. If you're upgrading from a previous version, run the following command to enable it: - - ```shell - npx storybook@latest automigrate - ``` - -Check the [Migration Guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#cra5-upgrade) for more information on how to set up Webpack 5. - -- For other installation issues, check the React README files for additional instructions: - - [React with Webpack](https://github.com/storybookjs/storybook/tree/next/code/frameworks/react-webpack5) - - [React with Vite](https://github.com/storybookjs/storybook/tree/next/code/frameworks/react-vite) diff --git a/docs/get-started/installation-problems/solid.mdx b/docs/get-started/installation-problems/solid.mdx deleted file mode 100644 index 9308bb9b154a..000000000000 --- a/docs/get-started/installation-problems/solid.mdx +++ /dev/null @@ -1,11 +0,0 @@ -- Add the `--type solid` flag to the installation command to set up Storybook manually: - - ```shell - npx storybook init --type solid - ``` - -- Storybook's CLI provides support for [Yarn](https://yarnpkg.com/), [npm](https://www.npmjs.com/), and [pnpm](https://pnpm.io/) package managers. If you have Yarn installed in your environment but prefer to use another as your default package manager add the `--package-manager` flag to your installation command. For example: - - ```shell - npx storybook init --package-manager=npm - ``` diff --git a/docs/get-started/installation-problems/svelte.mdx b/docs/get-started/installation-problems/svelte.mdx deleted file mode 100644 index d0bfd5284d68..000000000000 --- a/docs/get-started/installation-problems/svelte.mdx +++ /dev/null @@ -1,25 +0,0 @@ -- Add the `--type svelte` flag to the installation command to set up Storybook manually: - - ```shell - npx storybook@latest init --type svelte - ``` - -- Storybook's CLI provides support for [Yarn](https://yarnpkg.com/), [npm](https://www.npmjs.com/), and [pnpm](https://pnpm.io/) package managers. If you have Yarn installed in your environment but prefer to use another as your default package manager add the `--package-manager` flag to your installation command. For example: - - ```shell - npx storybook@latest init --package-manager=npm - ``` - -### Svelte Native - -To enable support for Svelte Native story format you'll need to make the following changes your Storybook configuration: -- Add the [`@storybook/addon-svelte-csf`](https://storybook.js.org/addons/@storybook/addon-svelte-csf/) addon as development dependency. -- Enable the addon in your Storybook configuration file (e.g., `.storybook/main.js`). -- Disable on demand story loading configuration property (e.g., `storyStoreV7`) in your Storybook configuration file. -- For issues with Svelte Native Story Format, check the [Svelte Story Format addon repository](https://github.com/storybookjs/addon-svelte-csf) for instructions. - - -- For other installation issues, check the Svelte README files for additional instructions: - - [Svelte with Webpack](https://github.com/storybookjs/storybook/tree/next/code/frameworks/svelte-webpack5) - - [Svelte with Vite](https://github.com/storybookjs/storybook/tree/next/code/frameworks/svelte-vite) - - [SvelteKit](https://github.com/storybookjs/storybook/tree/next/code/frameworks/sveltekit) diff --git a/docs/get-started/installation-problems/vue.mdx b/docs/get-started/installation-problems/vue.mdx deleted file mode 100644 index 1268f226a36b..000000000000 --- a/docs/get-started/installation-problems/vue.mdx +++ /dev/null @@ -1,19 +0,0 @@ -- Add the `--type vue` (for Vue 2), or `--type vue3` (for Vue 3) flag to the installation command to set up Storybook manually: - - ```shell - # For Vue 2 projects - npx storybook@latest init --type vue - - # For Vue 3 projects - npx storybook@latest init --type vue3 - ``` - -- Storybook's CLI provides support for [Yarn](https://yarnpkg.com/), [npm](https://www.npmjs.com/), and [pnpm](https://pnpm.io/) package managers. If you have Yarn installed in your environment but prefer to use another as your default package manager add the `--package-manager` flag to your installation command. For example: - - ```shell - npx storybook@latest init --package-manager=npm - ``` - -- For other installation issues, check the Vue README files for additional instructions: - - [Vue 3 with Webpack](https://github.com/storybookjs/storybook/tree/next/code/frameworks/vue3-webpack5) - - [Vue 3 with Vite](https://github.com/storybookjs/storybook/tree/next/code/frameworks/vue3-vite) diff --git a/docs/get-started/installation-problems/web-components.mdx b/docs/get-started/installation-problems/web-components.mdx deleted file mode 100644 index 1a25db5eadec..000000000000 --- a/docs/get-started/installation-problems/web-components.mdx +++ /dev/null @@ -1,9 +0,0 @@ -- Add the `--type web_components` flag to the installation command to set up Storybook manually: - - ```shell - npx storybook@latest init --type web_components - ``` - -- For other installation issues, check the Web Components README files for additional instructions: - - [Web Components with Webpack](https://github.com/storybookjs/storybook/tree/next/code/frameworks/web-components-webpack5) - - [Web Components with Vite](https://github.com/storybookjs/storybook/tree/next/code/frameworks/web-components-vite) diff --git a/docs/snippets/angular/angular-project-compodoc-config.json.mdx b/docs/snippets/angular/angular-project-compodoc-config.json.mdx new file mode 100644 index 000000000000..66d4130306ee --- /dev/null +++ b/docs/snippets/angular/angular-project-compodoc-config.json.mdx @@ -0,0 +1,50 @@ +```jsonc +// angular.json + +{ + "$schema": "./node_modules/@angular/cli/lib/config/schema.json", + "version": 1, + "newProjectRoot": "projects", + "projects": { + "your-project": { + "projectType": "application", + "schematics": {}, + "root": "", + "sourceRoot": "src", + "prefix": "app", + "architect": { + "storybook": { + "builder": "@storybook/angular:start-storybook", + "options": { + "configDir": ".storybook", + "browserTarget": "your-project:build", + "compodoc": true, + "compodocArgs": [ + "-e", + "json", + "-d", + "." // Add this line to introspect the relevant files starting from the root directory of your project. + ], + "port": 6006 + } + }, + "build-storybook": { + "builder": "@storybook/angular:build-storybook", + "options": { + "configDir": ".storybook", + "browserTarget": "your-project:build", + "compodoc": true, + "compodocArgs": [ + "-e", + "json", + "-d", + "." // Add this line to introspect the relevant files starting from the root directory of your project. + ], + "outputDir": "storybook-static" + } + } + } + } + } +} +``` diff --git a/docs/snippets/angular/compodoc-install.npm.js.mdx b/docs/snippets/angular/compodoc-install.npm.js.mdx new file mode 100644 index 000000000000..be943eda7dc2 --- /dev/null +++ b/docs/snippets/angular/compodoc-install.npm.js.mdx @@ -0,0 +1,3 @@ +```shell +npm install @compodoc/compodoc --save-dev +``` diff --git a/docs/snippets/angular/compodoc-install.pnpm.js.mdx b/docs/snippets/angular/compodoc-install.pnpm.js.mdx new file mode 100644 index 000000000000..116346afd228 --- /dev/null +++ b/docs/snippets/angular/compodoc-install.pnpm.js.mdx @@ -0,0 +1,3 @@ +```shell +pnpm add --save-dev @compodoc/compodo +``` diff --git a/docs/snippets/angular/compodoc-install.yarn.js.mdx b/docs/snippets/angular/compodoc-install.yarn.js.mdx new file mode 100644 index 000000000000..8a6ee05f79b4 --- /dev/null +++ b/docs/snippets/angular/compodoc-install.yarn.js.mdx @@ -0,0 +1,3 @@ +```shell +yarn add --dev @compodoc/compodoc +``` diff --git a/docs/snippets/angular/storybook-preview-compodoc-config.ts.mdx b/docs/snippets/angular/storybook-preview-compodoc-config.ts.mdx new file mode 100644 index 000000000000..658a8906b1e6 --- /dev/null +++ b/docs/snippets/angular/storybook-preview-compodoc-config.ts.mdx @@ -0,0 +1,24 @@ +```ts +// .storybook/preview.ts + +import type { Preview } from '@storybook/angular'; +import { setCompodocJson } from '@storybook/addon-docs/angular'; + +import docJson from '../documentation.json'; // The path to your generated json file from Compodoc contains all your documentation information. + +setCompodocJson(docJson); + +const preview: Preview = { + parameters: { + actions: { argTypesRegex: '^on[A-Z].*' }, + controls: { + matchers: { + color: /(background|color)$/i, + date: /Date$/, + }, + }, + }, +}; + +export default preview; +``` diff --git a/docs/snippets/common/init-command-custom-package-manager.npx.js.mdx b/docs/snippets/common/init-command-custom-package-manager.npx.js.mdx new file mode 100644 index 000000000000..e904617f28cb --- /dev/null +++ b/docs/snippets/common/init-command-custom-package-manager.npx.js.mdx @@ -0,0 +1,3 @@ +```shell +npx storybook@latest init --package-manager=npm +``` diff --git a/docs/snippets/common/init-command-custom-package-manager.pnpm.js.mdx b/docs/snippets/common/init-command-custom-package-manager.pnpm.js.mdx new file mode 100644 index 000000000000..abd51d256e80 --- /dev/null +++ b/docs/snippets/common/init-command-custom-package-manager.pnpm.js.mdx @@ -0,0 +1,3 @@ +```shell +pnpm dlx storybook@latest init --package-manager=npm +``` diff --git a/docs/snippets/common/init-command-custom-package-manager.yarn.js.mdx b/docs/snippets/common/init-command-custom-package-manager.yarn.js.mdx new file mode 100644 index 000000000000..d01bae571730 --- /dev/null +++ b/docs/snippets/common/init-command-custom-package-manager.yarn.js.mdx @@ -0,0 +1,3 @@ +```shell +yarn dlx storybook@latest init --package-manager=npm +``` diff --git a/docs/snippets/common/init-command-manual-framework.npx.js.mdx b/docs/snippets/common/init-command-manual-framework.npx.js.mdx new file mode 100644 index 000000000000..b0cbed167881 --- /dev/null +++ b/docs/snippets/common/init-command-manual-framework.npx.js.mdx @@ -0,0 +1,3 @@ +```shell +npx storybook@latest init --type solid +``` diff --git a/docs/snippets/common/init-command-manual-framework.pnpm.js.mdx b/docs/snippets/common/init-command-manual-framework.pnpm.js.mdx new file mode 100644 index 000000000000..483487b08ded --- /dev/null +++ b/docs/snippets/common/init-command-manual-framework.pnpm.js.mdx @@ -0,0 +1,3 @@ +```shell +pnpm dlx storybook@latest init --type solid +``` diff --git a/docs/snippets/common/init-command-manual-framework.yarn.js.mdx b/docs/snippets/common/init-command-manual-framework.yarn.js.mdx new file mode 100644 index 000000000000..b1152c869f0a --- /dev/null +++ b/docs/snippets/common/init-command-manual-framework.yarn.js.mdx @@ -0,0 +1,3 @@ +```shell +yarn dlx storybook@latest init --type solid +``` diff --git a/docs/snippets/ember/button-story-default-export-with-component.js.mdx b/docs/snippets/ember/button-story-default-export-with-component.js.mdx new file mode 100644 index 000000000000..c1e6396ad3e1 --- /dev/null +++ b/docs/snippets/ember/button-story-default-export-with-component.js.mdx @@ -0,0 +1,7 @@ +```js +// Button.stories.js + +export default { + component: 'button', +}; +``` diff --git a/docs/snippets/ember/storybook-ember-cli-build.js.mdx b/docs/snippets/ember/storybook-ember-cli-build.js.mdx new file mode 100644 index 000000000000..426e63872b82 --- /dev/null +++ b/docs/snippets/ember/storybook-ember-cli-build.js.mdx @@ -0,0 +1,17 @@ +```js +// ember-cli-build.js + +'use strict'; + +const EmberApp = require('ember-cli/lib/broccoli/ember-app'); + +module.exports = function (defaults) { + const app = new EmberApp(defaults, { + '@storybook/ember-cli-storybook': { + enableAddonDocsIntegration: true, + }, + }); + + return app.toTree(); +}; +``` diff --git a/docs/snippets/ember/storybook-preview-custom-metadata.js.mdx b/docs/snippets/ember/storybook-preview-custom-metadata.js.mdx new file mode 100644 index 000000000000..ec446d1559ab --- /dev/null +++ b/docs/snippets/ember/storybook-preview-custom-metadata.js.mdx @@ -0,0 +1,19 @@ +```js +// .storybook/preview.js + +import { setJSONDoc } from '@storybook/addon-docs/ember'; + +import docJson from '../dist/storybook-docgen/index.json'; +setJSONDoc(docJson); + +export default { + parameters: { + controls: { + matchers: { + color: /(background|color)$/i, + date: /Date$/, + }, + }, + }, +}; +``` diff --git a/docs/snippets/preact/button-story-default-export-with-component.js.mdx b/docs/snippets/preact/button-story-default-export-with-component.js.mdx new file mode 100644 index 000000000000..dfffb5de27e3 --- /dev/null +++ b/docs/snippets/preact/button-story-default-export-with-component.js.mdx @@ -0,0 +1,9 @@ +```js +// Button.stories.js|jsx + +import { Button } from './Button'; + +export default { + component: Button, +}; +``` diff --git a/docs/snippets/svelte/main-config-csf-addon-register.js.mdx b/docs/snippets/svelte/main-config-csf-addon-register.js.mdx new file mode 100644 index 000000000000..5559ac261ca1 --- /dev/null +++ b/docs/snippets/svelte/main-config-csf-addon-register.js.mdx @@ -0,0 +1,13 @@ +```js +// .storybook/main.js + +export default { + // Replace sveltekit with svelte-vite if you are not working with SvelteKit + framework: '@storybook/sveltekit', + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx|svelte)'], + addons: [ + // Other Storybook addons + '@storybook/addon-svelte-csf', //👈 The Svelte CSF addon goes here + ], +}; +``` diff --git a/docs/snippets/svelte/main-config-csf-addon-register.ts.mdx b/docs/snippets/svelte/main-config-csf-addon-register.ts.mdx new file mode 100644 index 000000000000..3221880ebb99 --- /dev/null +++ b/docs/snippets/svelte/main-config-csf-addon-register.ts.mdx @@ -0,0 +1,17 @@ +```ts +// .storybook/main.ts + +// Replace sveltekit with svelte-vite if you are not working with SvelteKit +import type { StorybookConfig } from '@storybook/sveltekit'; + +const config: StorybookConfig = { + framework: '@storybook/sveltekit', + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx|svelte)'], + addons: [ + // Other Storybook addons + '@storybook/addon-svelte-csf', //👈 The Svelte CSF addon goes here + ], +}; + +export default config; +``` diff --git a/docs/snippets/svelte/svelte-csf-addon-install.npm.js.mdx b/docs/snippets/svelte/svelte-csf-addon-install.npm.js.mdx new file mode 100644 index 000000000000..574d63651863 --- /dev/null +++ b/docs/snippets/svelte/svelte-csf-addon-install.npm.js.mdx @@ -0,0 +1,3 @@ +```shell +npm install @storybook/addon-svelte-csf --save-dev +``` diff --git a/docs/snippets/svelte/svelte-csf-addon-install.pnpm.js.mdx b/docs/snippets/svelte/svelte-csf-addon-install.pnpm.js.mdx new file mode 100644 index 000000000000..4ff9be66f107 --- /dev/null +++ b/docs/snippets/svelte/svelte-csf-addon-install.pnpm.js.mdx @@ -0,0 +1,3 @@ +```shell +pnpm add --save-dev @storybook/addon-svelte-csf +``` diff --git a/docs/snippets/svelte/svelte-csf-addon-install.yarn.js.mdx b/docs/snippets/svelte/svelte-csf-addon-install.yarn.js.mdx new file mode 100644 index 000000000000..5b3e6dff23f6 --- /dev/null +++ b/docs/snippets/svelte/svelte-csf-addon-install.yarn.js.mdx @@ -0,0 +1,3 @@ +```shell +yarn add --dev @storybook/addon-svelte-csf +``` diff --git a/docs/snippets/web-components/button-story-default-export-with-component.ts.mdx b/docs/snippets/web-components/button-story-default-export-with-component.ts.mdx new file mode 100644 index 000000000000..805431b359c0 --- /dev/null +++ b/docs/snippets/web-components/button-story-default-export-with-component.ts.mdx @@ -0,0 +1,11 @@ +```ts +// Button.stories.ts + +import type { Meta } from '@storybook/web-components'; + +export default { + component: 'demo-button', +}; + +export default meta; +``` diff --git a/docs/snippets/web-components/component-story-custom-args-complex.js.mdx b/docs/snippets/web-components/component-story-custom-args-complex.js.mdx new file mode 100644 index 000000000000..0bd0906b20ba --- /dev/null +++ b/docs/snippets/web-components/component-story-custom-args-complex.js.mdx @@ -0,0 +1,42 @@ +```js +// Button.stories.js + +import { html } from 'lit'; + +export default { + component: 'custom-component', + //👇 Creates specific argTypes + argTypes: { + propertyA: { + options: ['Item One', 'Item Two', 'Item Three'], + control: { type: 'select' }, // Automatically inferred when 'options' is defined + }, + propertyB: { + options: ['Another Item One', 'Another Item Two', 'Another Item Three'], + }, + }, +}; + +const someFunction = (valuePropertyA, valuePropertyB) => { + // Do some logic here +}; + +export const ExampleStory = { + render: ({ propertyA, propertyB }) => { + //👇 Assigns the function result to a variable + const someFunctionResult = someFunction(propertyA, propertyB); + + return html` + + `; + }, + args: { + propertyA: 'Item One', + propertyB: 'Another Item One', + }, +}; +``` diff --git a/docs/snippets/web-components/component-story-custom-args-complex.ts.mdx b/docs/snippets/web-components/component-story-custom-args-complex.ts.mdx new file mode 100644 index 000000000000..b772ef0301cc --- /dev/null +++ b/docs/snippets/web-components/component-story-custom-args-complex.ts.mdx @@ -0,0 +1,47 @@ +```ts +// Button.stories.ts + +import type { Meta, StoryObj } from '@storybook/web-components'; + +import { html } from 'lit'; + +const meta: Meta = { + component: 'custom-component', + //👇 Creates specific argTypes with options + argTypes: { + propertyA: { + options: ['Item One', 'Item Two', 'Item Three'], + control: { type: 'select' }, // Automatically inferred when 'options' is defined + }, + propertyB: { + options: ['Another Item One', 'Another Item Two', 'Another Item Three'], + }, + }, +}; + +export default meta; +type Story = StoryObj; + +const someFunction = (valuePropertyA: any, valuePropertyB: any) => { + // Do some logic here +}; + +export const ExampleStory: Story = { + render: ({ propertyA, propertyB }) => { + //👇 Assigns the function result to a variable + const someFunctionResult = someFunction(propertyA, propertyB); + + return html` + + `; + }, + args: { + propertyA: 'Item One', + propertyB: 'Another Item One', + }, +}; +``` diff --git a/docs/snippets/web-components/storybook-preview-custom-elements-config.js.mdx b/docs/snippets/web-components/storybook-preview-custom-elements-config.js.mdx new file mode 100644 index 000000000000..10b4d63d5c01 --- /dev/null +++ b/docs/snippets/web-components/storybook-preview-custom-elements-config.js.mdx @@ -0,0 +1,19 @@ +```js +// .storybook/preview.js + +import { setCustomElementsManifest } from '@storybook/web-components'; +import customElements from '../custom-elements.json'; + +setCustomElementsManifest(customElements); + +export default { + parameters: { + controls: { + matchers: { + color: /(background|color)$/i, + date: /Date$/, + }, + }, + }, +}; +``` diff --git a/docs/snippets/web-components/storybook-preview-custom-elements-config.ts.mdx b/docs/snippets/web-components/storybook-preview-custom-elements-config.ts.mdx new file mode 100644 index 000000000000..df8a1e374053 --- /dev/null +++ b/docs/snippets/web-components/storybook-preview-custom-elements-config.ts.mdx @@ -0,0 +1,24 @@ +```ts +// .storybook/preview.ts + +import type { Preview } from '@storybook/web-components'; +import { setCustomElementsManifest } from '@storybook/web-components'; + +import customElements from '../custom-elements.json'; + +setCustomElementsManifest(customElements); + +const preview: Preview = { + parameters: { + actions: { argTypesRegex: '^on[A-Z].*' }, + controls: { + matchers: { + color: /(background|color)$/i, + date: /Date$/i, + }, + }, + }, +}; + +export default preview; +``` diff --git a/docs/writing-stories/index.md b/docs/writing-stories/index.md index c938a3f60929..a270dd95b1e1 100644 --- a/docs/writing-stories/index.md +++ b/docs/writing-stories/index.md @@ -39,6 +39,7 @@ The _default_ export metadata controls how Storybook lists your stories and prov 'svelte/button-story-default-export-with-component.js.mdx', 'svelte/button-story-default-export-with-component.ts.mdx', 'web-components/button-story-default-export-with-component.js.mdx', + 'web-components/button-story-default-export-with-component.ts.mdx', 'html/button-story-default-export.js.mdx', 'html/button-story-default-export.ts.mdx', 'solid/button-story-default-export-with-component.js.mdx',