diff --git a/.circleci/config.yml b/.circleci/config.yml index b34288f775cb..cb087540361f 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -17,7 +17,7 @@ executors: default: "small" working_directory: /tmp/storybook docker: - - image: cimg/node:18.18.0 + - image: cimg/node:18.19.1 environment: NODE_OPTIONS: --max_old_space_size=6144 resource_class: <> @@ -30,7 +30,7 @@ executors: default: "small" working_directory: /tmp/storybook docker: - - image: cimg/node:18.18.0-browsers + - image: cimg/node:18.19.1-browsers environment: NODE_OPTIONS: --max_old_space_size=6144 resource_class: <> diff --git a/.nvmrc b/.nvmrc index 87ec8842b158..3c5535cf60a0 100644 --- a/.nvmrc +++ b/.nvmrc @@ -1 +1 @@ -18.18.2 +18.19.1 diff --git a/CHANGELOG.md b/CHANGELOG.md index 2de9a1f7882f..61ad5d1f5e1e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,10 @@ +## 8.0.6 + +- CLI: Add --config-dir flag to migrate command - [#26721](https://github.com/storybookjs/storybook/pull/26721), thanks @yannbf! +- Next.js: Fix next/font usage on Windows machines - [#26700](https://github.com/storybookjs/storybook/pull/26700), thanks @valentinpalkovic! +- Next.js: Support path aliases when no base url is set - [#26651](https://github.com/storybookjs/storybook/pull/26651), thanks @yannbf! +- Webpack: Fix sourcemap generation in webpack react-docgen-loader - [#26676](https://github.com/storybookjs/storybook/pull/26676), thanks @valentinpalkovic! + ## 8.0.5 - Addon-docs: Fix `react-dom/server` imports breaking stories and docs - [#26557](https://github.com/storybookjs/storybook/pull/26557), thanks @JReinhold! diff --git a/code/frameworks/nextjs/src/css/webpack.ts b/code/frameworks/nextjs/src/css/webpack.ts index 75718527e7dd..f6c7d7838f0a 100644 --- a/code/frameworks/nextjs/src/css/webpack.ts +++ b/code/frameworks/nextjs/src/css/webpack.ts @@ -36,7 +36,7 @@ export const configureCss = (baseConfig: WebpackConfig, nextConfig: NextConfig): ], // We transform the "target.css" files from next.js into Javascript // for Next.js to support fonts, so it should be ignored by the css-loader. - exclude: /next\/.*\/target.css$/, + exclude: /next(\\|\/|\\\\).*(\\|\/|\\\\)target\.css$/, }; } }); diff --git a/code/frameworks/nextjs/src/font/webpack/configureNextFont.ts b/code/frameworks/nextjs/src/font/webpack/configureNextFont.ts index b1e3851611d6..bd3f1640ff36 100644 --- a/code/frameworks/nextjs/src/font/webpack/configureNextFont.ts +++ b/code/frameworks/nextjs/src/font/webpack/configureNextFont.ts @@ -7,7 +7,7 @@ export function configureNextFont(baseConfig: Configuration, isSWC?: boolean) { if (isSWC) { baseConfig.module?.rules?.push({ - test: /next\/.*\/target.css$/, + test: /next(\\|\/|\\\\).*(\\|\/|\\\\)target\.css$/, loader: fontLoaderPath, }); } else { diff --git a/code/frameworks/nextjs/src/font/webpack/loader/local/get-font-face-declarations.ts b/code/frameworks/nextjs/src/font/webpack/loader/local/get-font-face-declarations.ts index f3f35c2fc065..e980d15b0e3d 100644 --- a/code/frameworks/nextjs/src/font/webpack/loader/local/get-font-face-declarations.ts +++ b/code/frameworks/nextjs/src/font/webpack/loader/local/get-font-face-declarations.ts @@ -39,13 +39,9 @@ export async function getFontFaceDeclarations( .map(({ prop, value }: { prop: string; value: string }) => `${prop}: ${value};`) .join('\n'); - const arePathsWin32Format = /^[a-z]:\\/iu.test(options.filename); - const cleanWin32Path = (pathString: string): string => - arePathsWin32Format ? pathString.replace(/\\/gu, '/') : pathString; - const getFontFaceCSS = () => { if (typeof localFontSrc === 'string') { - const localFontPath = cleanWin32Path(path.join(parentFolder, localFontSrc)); + const localFontPath = path.join(parentFolder, localFontSrc).replaceAll('\\', '/'); return `@font-face { font-family: ${id}; @@ -55,7 +51,7 @@ export async function getFontFaceDeclarations( } return localFontSrc .map((font) => { - const localFontPath = cleanWin32Path(path.join(parentFolder, font.path)); + const localFontPath = path.join(parentFolder, font.path).replaceAll('\\', '/'); return `@font-face { font-family: ${id}; diff --git a/code/frameworks/nextjs/src/font/webpack/loader/storybook-nextjs-font-loader.ts b/code/frameworks/nextjs/src/font/webpack/loader/storybook-nextjs-font-loader.ts index 2110701aae61..055d934f57a4 100644 --- a/code/frameworks/nextjs/src/font/webpack/loader/storybook-nextjs-font-loader.ts +++ b/code/frameworks/nextjs/src/font/webpack/loader/storybook-nextjs-font-loader.ts @@ -3,6 +3,7 @@ import { getFontFaceDeclarations as getLocalFontFaceDeclarations } from './local import type { LoaderOptions } from './types'; import { getCSSMeta } from './utils/get-css-meta'; import { setFontDeclarationsInHead } from './utils/set-font-declarations-in-head'; +import path from 'path'; type FontFaceDeclaration = { id: string; @@ -39,11 +40,19 @@ export default async function storybookNextjsFontLoader(this: any) { let fontFaceDeclaration: FontFaceDeclaration | undefined; - if (options.source.endsWith('next/font/google') || options.source.endsWith('@next/font/google')) { + const pathSep = path.sep; + + if ( + options.source.endsWith(`next${pathSep}font${pathSep}google`) || + options.source.endsWith(`@next${pathSep}font${pathSep}google`) + ) { fontFaceDeclaration = await getGoogleFontFaceDeclarations(options); } - if (options.source.endsWith('next/font/local') || options.source.endsWith('@next/font/local')) { + if ( + options.source.endsWith(`next${pathSep}font${pathSep}local`) || + options.source.endsWith(`@next${pathSep}font${pathSep}local`) + ) { fontFaceDeclaration = await getLocalFontFaceDeclarations(options, rootCtx, swcMode); } diff --git a/code/frameworks/nextjs/src/imports/webpack.ts b/code/frameworks/nextjs/src/imports/webpack.ts index 0b7a45b13bc8..57d837d0fdb2 100644 --- a/code/frameworks/nextjs/src/imports/webpack.ts +++ b/code/frameworks/nextjs/src/imports/webpack.ts @@ -11,8 +11,8 @@ export const configureImports = ({ }): void => { const configLoadResult = loadConfig(configDir); - if (configLoadResult.resultType === 'failed' || !configLoadResult.baseUrl) { - // either not a typescript project or tsconfig contains no baseUrl + if (configLoadResult.resultType === 'failed') { + // either not a typescript project or tsconfig is not found - we bail return; } diff --git a/code/lib/cli/src/generate.ts b/code/lib/cli/src/generate.ts index 53c6259dc35b..5a75f11c6173 100644 --- a/code/lib/cli/src/generate.ts +++ b/code/lib/cli/src/generate.ts @@ -126,6 +126,7 @@ command('migrate [migration]') .option('-l --list', 'List available migrations') .option('-g --glob ', 'Glob for files upon which to apply the migration', '**/*.js') .option('-p --parser ', 'jscodeshift parser') + .option('-c, --config-dir ', 'Directory where to load Storybook configurations from') .option( '-n --dry-run', 'Dry run: verify the migration exists and show the files to which it will be applied' @@ -142,7 +143,6 @@ command('migrate [migration]') list, rename, parser, - logger: consoleLogger, }).catch((err) => { logger.error(err); process.exit(1); diff --git a/code/lib/cli/src/migrate.ts b/code/lib/cli/src/migrate.ts index 29ee10dc82a3..fc85c75d9609 100644 --- a/code/lib/cli/src/migrate.ts +++ b/code/lib/cli/src/migrate.ts @@ -11,7 +11,25 @@ import { getStorybookVersionSpecifier } from './helpers'; const logger = console; -export async function migrate(migration: any, { glob, dryRun, list, rename, parser }: any) { +type CLIOptions = { + glob: string; + configDir?: string; + dryRun?: boolean; + list?: string[]; + /** + * Rename suffix of matching files after codemod has been applied, e.g. ".js:.ts" + */ + rename?: string; + /** + * jscodeshift parser + */ + parser?: 'babel' | 'babylon' | 'flow' | 'ts' | 'tsx'; +}; + +export async function migrate( + migration: any, + { glob, dryRun, list, rename, parser, configDir: userSpecifiedConfigDir }: CLIOptions +) { if (list) { listCodemods().forEach((key: any) => logger.log(key)); } else if (migration) { @@ -19,13 +37,14 @@ export async function migrate(migration: any, { glob, dryRun, list, rename, pars const packageManager = JsPackageManagerFactory.getPackageManager(); const [packageJson, storybookVersion] = await Promise.all([ - // packageManager.retrievePackageJson(), getCoercedStorybookVersion(packageManager), ]); - const { configDir: inferredConfigDir, mainConfig: mainConfigPath } = - getStorybookInfo(packageJson); - const configDir = inferredConfigDir || '.storybook'; + const { configDir: inferredConfigDir, mainConfig: mainConfigPath } = getStorybookInfo( + packageJson, + userSpecifiedConfigDir + ); + const configDir = userSpecifiedConfigDir || inferredConfigDir || '.storybook'; // GUARDS if (!storybookVersion) { diff --git a/code/package.json b/code/package.json index 4c97decd5574..4813791fa111 100644 --- a/code/package.json +++ b/code/package.json @@ -295,5 +295,6 @@ "Dependency Upgrades" ] ] - } + }, + "deferredNextVersion": "8.0.6" } diff --git a/code/presets/react-webpack/src/loaders/react-docgen-loader.ts b/code/presets/react-webpack/src/loaders/react-docgen-loader.ts index 15b71f19bfd5..ac83e37982de 100644 --- a/code/presets/react-webpack/src/loaders/react-docgen-loader.ts +++ b/code/presets/react-webpack/src/loaders/react-docgen-loader.ts @@ -114,7 +114,10 @@ export default async function reactDocgenLoader( } }); - const map = magicString.generateMap({ hires: true }); + const map = magicString.generateMap({ + includeContent: true, + source: this.resourcePath, + }); callback(null, magicString.toString(), map); } catch (error: any) { if (error.code === ERROR_CODES.MISSING_DEFINITION) { diff --git a/docs/api/cli-options.md b/docs/api/cli-options.md index 3aa9f0a3f0a1..24c0c5d8b002 100644 --- a/docs/api/cli-options.md +++ b/docs/api/cli-options.md @@ -30,25 +30,33 @@ storybook dev [options] Options include: -| Option | Description | -| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `--help` | Output usage information
`storybook dev --help` | -| `-V`, `--version` | Output the version number
`storybook dev -V` | -| `-p`, `--port [number]` | Port to run Storybook
`storybook dev -p 9009` | -| `-h`, `--host [string]` | Host to run Storybook
`storybook dev -h my-host.com` | -| `-c`, `--config-dir [dir-name]` | Directory where to load Storybook configurations from
`storybook dev -c .storybook` | -| `--https` | Serve Storybook over HTTPS. Note: You must provide your own certificate information
`storybook dev --https` | -| `--ssl-ca` | Provide an SSL certificate authority. (Optional with --https, required if using a self-signed certificate)
`storybook dev --ssl-ca my-certificate` | -| `--ssl-cert` | Provide an SSL certificate. (Required with --https)
`storybook dev --ssl-cert my-ssl-certificate` | -| `--ssl-key` | Provide an SSL key. (Required with --https)
`storybook dev --ssl-key my-ssl-key` | -| `--smoke-test` | Exit after successful start
`storybook dev --smoke-test` | -| `--ci` | CI mode (skip interactive prompts, don't open browser)
`storybook dev --ci` | -| `--no-open` | Do not open Storybook automatically in the browser
`storybook dev --no-open` | -| `--quiet` | Suppress verbose build output
`storybook dev --quiet` | -| `--debug-webpack` | Display final webpack configurations for debugging purposes
`storybook dev --debug-webpack` | -| `--stats-json` | Write stats JSON to disk
`storybook dev ---stats-json /tmp/stats`
NOTE: only works for webpack. | -| `--docs` | Starts Storybook in documentation mode. Learn more about it in [here](../writing-docs/build-documentation.md#preview-storybooks-documentation)
`storybook dev --docs` | -| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.md)
`storybook dev --disable-telemetry` | +| Option | Description | +| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `--help` | Output usage information
`storybook dev --help` | +| `-V`, `--version` | Output the version number
`storybook dev -V` | +| `-p`, `--port [number]` | Port to run Storybook
`storybook dev -p 9009` | +| `--exact-port [number]` | Attempts to run Storybook on the exact port number specified.
If the port is already in use, Storybook will exit with an error message
`storybook dev --exact-port 9009` | +| `-h`, `--host [string]` | Host to run Storybook
`storybook dev -h my-host.com` | +| `-c`, `--config-dir [dir-name]` | Directory where to load Storybook configurations from
`storybook dev -c .storybook` | +| `--loglevel [level]` | Controls level of logging during build.
Available options: `silly`, `verbose`, `info` (default), `warn`, `error`, `silent`
`storybook dev --loglevel warn` | +| `--https` | Serve Storybook over HTTPS. Note: You must provide your own certificate information
`storybook dev --https` | +| `--ssl-ca` | Provide an SSL certificate authority. (Optional with --https, required if using a self-signed certificate)
`storybook dev --ssl-ca my-certificate` | +| `--ssl-cert` | Provide an SSL certificate. (Required with --https)
`storybook dev --ssl-cert my-ssl-certificate` | +| `--ssl-key` | Provide an SSL key. (Required with --https)
`storybook dev --ssl-key my-ssl-key` | +| `--smoke-test` | Exit after successful start
`storybook dev --smoke-test` | +| `--ci` | CI mode (skip interactive prompts, don't open browser)
`storybook dev --ci` | +| `--no-open` | Do not open Storybook automatically in the browser
`storybook dev --no-open` | +| `--quiet` | Suppress verbose build output
`storybook dev --quiet` | +| `--debug` | Outputs more logs in the CLI to assist debugging
`storybook dev --debug` | +| `--debug-webpack` | Display final webpack configurations for debugging purposes
`storybook dev --debug-webpack` | +| `--stats-json [dir-name]` | Write stats JSON to disk
Requires Webpack
`storybook dev --stats-json /tmp/stats` | +| `--no-version-updates` | Skips Storybook's update check
`storybook dev --no-version-updates` | +| `--docs` | Starts Storybook in documentation mode. Learn more about it in [here](../writing-docs/build-documentation.md#preview-storybooks-documentation)
`storybook dev --docs` | +| `--initial-path [path]` | Configures the URL Storybook should open when it opens the browser for the first time
`storybook dev --initial-path=/docs/getting-started--docs` | +| `--preview-url [path]` | Overrides the default Storybook preview with a custom built preview URL
`storybook dev --preview-url=http://localhost:1337/external-iframe.html` | +| `--force-build-preview` | Forcefully builds Storybook's preview iframe.
Useful if you're experiencing issues, or combined with `--preview-url` to ensure the preview is up-to-date
`storybook dev --force-build-preview` | +| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#how-to-opt-out)
`storybook dev --disable-telemetry` | +| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#crash-reports-disabled-by-default)
`storybook dev --enable-crash-reports` | @@ -66,21 +74,23 @@ storybook build [options] Options include: -| Option | Description | -| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `-h`, `--help` | Output usage information
`storybook build --help` | -| `-V`, `--version` | Output the version number
`storybook build -V` | -| `-o`, `--output-dir [dir-name]` | Directory where to store built files
`storybook build -o /my-deployed-storybook` | -| `-c`, `--config-dir [dir-name]` | Directory where to load Storybook configurations from
`storybook build -c .storybook` | -| `--loglevel [level]` | Controls level of logging during build.
Available options: `silly`, `verbose`, `info` (default), `warn`, `error`, `silent`
`storybook build --loglevel warn` | -| `--quiet` | Suppress verbose build output
`storybook build --quiet` | -| `--debug-webpack` | Display final webpack configurations for debugging purposes
`storybook build --debug-webpack` | -| `---stats-json` | Write stats JSON to disk
`storybook build -stats-json /my-storybook/-stats` | -| `--docs` | Builds Storybook in documentation mode. Learn more about it in [here](../writing-docs/build-documentation.md#publish-storybooks-documentation)
`storybook build --docs` | -| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.md).
`storybook build --disable-telemetry` | -| `--test` | Optimize Storybook's production build for performance and tests by removing unnecessary features with the `test` option. Learn more [here](../api/main-config-build.md).
`storybook build --test` | - - +| Option | Description | +| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-h`, `--help` | Output usage information
`storybook build --help` | +| `-V`, `--version` | Output the version number
`storybook build -V` | +| `-o`, `--output-dir [dir-name]` | Directory where to store built files
`storybook build -o /my-deployed-storybook` | +| `-c`, `--config-dir [dir-name]` | Directory where to load Storybook configurations from
`storybook build -c .storybook` | +| `--loglevel [level]` | Controls level of logging during build.
Available options: `silly`, `verbose`, `info` (default), `warn`, `error`, `silent`
`storybook build --loglevel warn` | +| `--quiet` | Suppress verbose build output
`storybook build --quiet` | +| `--debug` | Outputs more logs in the CLI to assist debugging
`storybook build --debug` | +| `--debug-webpack` | Display final webpack configurations for debugging purposes
`storybook build --debug-webpack` | +| `--stats-json [dir-name]` | Write stats JSON to disk
Requires Webpack
`storybook build --stats-json /tmp/stats` | +| `--docs` | Builds Storybook in documentation mode. Learn more about it in [here](../writing-docs/build-documentation.md#publish-storybooks-documentation)
`storybook build --docs` | +| `--test` | Optimize Storybook's production build for performance and tests by removing unnecessary features with the `test` option. Learn more [here](../api/main-config-build.md).
`storybook build --test` | +| `--preview-url [path]` | Overrides the default Storybook preview with a custom built preview URL
`storybook build --preview-url=http://localhost:1337/external-iframe.html` | +| `--force-build-preview` | Forcefully builds Storybook's preview iframe.
Useful if you're experiencing issues, or combined with `--preview-url` to ensure the preview is up-to-date
`storybook build --force-build-preview` | +| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#how-to-opt-out)
`storybook build --disable-telemetry` | +| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#crash-reports-disabled-by-default)
`storybook build --enable-crash-reports` | ### `init` @@ -94,15 +104,20 @@ For example, `storybook@latest init` will install the latest version of Storyboo Options include: -| Option | Description | -| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `-b`, `--builder` | Defines the [builder](../builders/index.md) to use for your Storybook instance
`storybook init --builder webpack5` | -| `-f`,`--force` | Forcefully installs Storybook into your project, prompting you to overwrite existing files
`storybook init --force` | -| `-s`, `--skip-install` | Skips the dependency installation step. Used only when you need to configure Storybook manually
`storybook init --skip-install` | -| `-t`, `--type` | Defines the [framework](../configure/frameworks.md) to use for your Storybook instance
`storybook init --type solid` | -| `-y`, `--yes` | Skips interactive prompts and automatically installs Storybook per specified version
`storybook init --yes` | -| `--package-manager` | Sets the package manager to use when installing the addon.
Available package managers include `npm`, `yarn`, and `pnpm`
`storybook init --package-manager pnpm` | -| `--use-pnp` | Enables [Plug'n'Play](https://yarnpkg.com/features/pnp) support for Yarn. This option is only available when using Yarn as your package manager
`storybook init --use-pnp` | +| Option | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-h`, `--help` | Output usage information
`storybook init --help` | +| `-b`, `--builder` | Defines the [builder](../builders/index.md) to use for your Storybook instance
`storybook init --builder webpack5` | +| `-f`,`--force` | Forcefully installs Storybook into your project, prompting you to overwrite existing files
`storybook init --force` | +| `-s`, `--skip-install` | Skips the dependency installation step. Used only when you need to configure Storybook manually
`storybook init --skip-install` | +| `-t`, `--type` | Defines the [framework](../configure/frameworks.md) to use for your Storybook instance
`storybook init --type solid` | +| `-y`, `--yes` | Skips interactive prompts and automatically installs Storybook per specified version
`storybook init --yes` | +| `--package-manager` | Sets the package manager to use when installing Storybook.
Available package managers include `npm`, `yarn`, and `pnpm`
`storybook init --package-manager pnpm` | +| `--use-pnp` | Enables [Plug'n'Play](https://yarnpkg.com/features/pnp) support for Yarn. This option is only available when using Yarn as your package manager
`storybook init --use-pnp` | +| `-p`, `--parser` | Sets the [jscodeshift parser](https://github.com/facebook/jscodeshift#parser).
Available parsers include `babel`, `babylon`, `flow`, `ts`, and `tsx`
`storybook init --parser tsx` | +| `--debug` | Outputs more logs in the CLI to assist debugging
`storybook init --debug` | +| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#how-to-opt-out)
`storybook init --disable-telemetry` | +| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#crash-reports-disabled-by-default)
`storybook init --enable-crash-reports` | ### `add` @@ -116,8 +131,10 @@ Options include: | Option | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-h`, `--help` | Output usage information
`storybook add --help` | | `--package-manager` | Sets the package manager to use when installing the addon.
Available package managers include `npm`, `yarn`, and `pnpm`
`storybook add [addon] --package-manager pnpm` | | `-s`, `--skip-postinstall` | Skips post-install configuration. Used only when you need to configure the addon yourself
`storybook add [addon] --skip-postinstall` | +| `--debug` | Outputs more logs in the CLI to assist debugging
`storybook add --debug` | ### `remove` @@ -129,9 +146,13 @@ storybook remove [addon] [options] Options include: -| Option | Description | -| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `--package-manager` | Sets the package manager to use when removing the addon.
Available package managers include `npm`, `yarn`, and `pnpm`
`storybook remove [addon]--package-manager pnpm` | +| Option | Description | +| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-h`, `--help` | Output usage information
`storybook remove --help` | +| `--package-manager` | Sets the package manager to use when removing the addon.
Available package managers include `npm`, `yarn`, and `pnpm`
`storybook remove [addon]--package-manager pnpm` | +| `--debug` | Outputs more logs in the CLI to assist debugging
`storybook remove --debug` | +| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#how-to-opt-out)
`storybook remove --disable-telemetry` | +| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#crash-reports-disabled-by-default)
`storybook remove --enable-crash-reports` | ### `upgrade` @@ -145,13 +166,73 @@ For example, `storybook@latest upgrade --dry-run` will perform a dry run (no act Options include: -| Option | Description | -| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `-c`, `--config-dir` | Directory where to load Storybook configurations from
`storybook upgrade --config-dir .storybook` | -| `-n`, `--dry-run` | Checks for version upgrades without installing them
`storybook upgrade --dry-run` | -| `-s`, `--skip-check` | Skips the migration check step during the upgrade process
`storybook upgrade --skip-check` | -| `-y`, `--yes` | Skips interactive prompts and automatically upgrades Storybook to the latest version
`storybook upgrade --yes` | -| `--package-manager` | Sets the package manager to use when installing the addon.
Available package managers include `npm`, `yarn`, and `pnpm`
`storybook upgrade --package-manager pnpm` | +| Option | Description | +| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-h`, `--help` | Output usage information
`storybook upgrade --help` | +| `-c`, `--config-dir` | Directory where to load Storybook configurations from
`storybook upgrade --config-dir .storybook` | +| `-n`, `--dry-run` | Checks for version upgrades without installing them
`storybook upgrade --dry-run` | +| `-s`, `--skip-check` | Skips the migration check step during the upgrade process
`storybook upgrade --skip-check` | +| `-y`, `--yes` | Skips interactive prompts and automatically upgrades Storybook to the latest version
`storybook upgrade --yes` | +| `-f`,`--force` | Force the upgrade, skipping autoblockers check
`storybook upgrade --force` | +| `--package-manager` | Sets the package manager to use when upgrading Storybook.
Available package managers include `npm`, `yarn`, and `pnpm`
`storybook upgrade --package-manager pnpm` | +| `--debug` | Outputs more logs in the CLI to assist debugging
`storybook upgrade --debug` | +| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#how-to-opt-out)
`storybook upgrade --disable-telemetry` | +| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#crash-reports-disabled-by-default)
`storybook upgrade --enable-crash-reports` | + +### `migrate` + +Runs the provided codemod to ensure your Storybook project is compatible with the specified version. Read more in the [migration guide](../configure/upgrading.md). + +```shell +storybook[@version] migrate [codemod] [options] +``` + + + +The command requires the codemod name (e.g., `csf-2-to-3`) as an argument to apply the necessary changes to your project. You can find the list of available codemods by running `storybook migrate --list`. + + + +For example, `storybook@latest migrate csf-2-to-3 --dry-run`, checks your project to verify if the codemod can be applied without making any changes, providing you with a report of which files would be affected. + +Options include: + +| Option | Description | +| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-h`, `--help` | Output usage information
`storybook migrate --help` | +| `-c`, `--config-dir` | Directory where to load Storybook configurations from
`storybook migrate --config-dir .storybook` | +| `-n`, `--dry-run` | Verify the migration exists and show the files to which it will be applied
`storybook migrate --dry-run` | +| `-l`, `--list` | Shows a list of available codemods
`storybook migrate --list` | +| `-g`, `--glob` | Glob for files upon which to apply the codemods
`storybook migrate --glob src/**/*.stories.tsx` | +| `-p`, `--parser` | Sets the [jscodeshift parser](https://github.com/facebook/jscodeshift#parser).
Available parsers include `babel`, `babylon`, `flow`, `ts`, and `tsx`
`storybook migrate --parser tsx` | +| `-r`, `--rename [from-to]` | Renames the files affected by the codemod to include the provided suffix
`storybook migrate --rename ".js:.ts"` | +| `--debug` | Outputs more logs in the CLI to assist debugging
`storybook migrate --debug` | + +### `automigrate` + +Perform standard configuration checks to determine if your Storybook project can be automatically migrated to the specified version. Read more in the [migration guide](../configure/upgrading.md#automigrate-script). + +```shell +storybook[@version] automigrate [fixId] [options] +``` + +For example, `storybook@latest automigrate --dry-run` scans your project for potential migrations that can be applied automatically without making any changes. + +Options include: + +| Option | Description | +| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-h`, `--help` | Output usage information
`storybook automigrate --help` | +| `-c`, `--config-dir` | Directory where to load Storybook configurations from
`storybook automigrate --config-dir .storybook` | +| `-n`, `--dry-run` | Checks for available migrations without applying them
`storybook automigrate --dry-run` | +| `-s`, `--skip-install` | Skip installing dependencies whenever applicable
`storybook automigrate --skip-install` | +| `-y`, `--yes` | Applies available migrations automatically without prompting for confirmation
`storybook automigrate --yes` | +| `-l`, `--list` | Shows a list of available automigrations
`storybook automigrate --list` | +| `--package-manager` | Sets the package manager to use when running the auto migration.
Available package managers include `npm`, `yarn`, and `pnpm`
`storybook automigrate --package-manager pnpm` | +| `--renderer` | Specifies Storybook's renderer to use when running the automigration.
Useful for monorepo environments where multiple Storybook instances can exist in the same project
`storybook automigrate --renderer vue` | +| `--debug` | Outputs more logs in the CLI to assist debugging
`storybook automigrate --debug` | +| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#how-to-opt-out)
`storybook automigrate --disable-telemetry` | +| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#crash-reports-disabled-by-default)
`storybook automigrate --enable-crash-reports` | ### `doctor` @@ -165,8 +246,10 @@ Options include: | Option | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-h`, `--help` | Output usage information
`storybook doctor --help` | | `-c`, `--config-dir` | Directory where to load Storybook configurations from
`storybook doctor --config-dir .storybook` | | `--package-manager` | Sets the package manager to use when running the health check.
Available package managers include `npm`, `yarn`, and `pnpm`
`storybook doctor --package-manager pnpm` | +| `--debug` | Outputs more logs in the CLI to assist debugging
`storybook doctor --debug` | ### `info` @@ -219,10 +302,14 @@ The `framework-filter` argument is optional and can filter the list of available Options include: -| Option | Description | -| --------------------------- | ---------------------------------------------------------------------------------------------------- | -| `-o`, `--output [dir-name]` | Configures the location of the sandbox project
`storybook sandbox --output /my-sandbox-project` | -| `--no-init` | Generates a sandbox project without without initializing Storybook
`storybook sandbox --no-init` | +| Option | Description | +| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-h`, `--help` | Output usage information
`storybook sandbox --help` | +| `-o`, `--output [dir-name]` | Configures the location of the sandbox project
`storybook sandbox --output /my-sandbox-project` | +| `--no-init` | Generates a sandbox project without without initializing Storybook
`storybook sandbox --no-init` | +| `--debug` | Outputs more logs in the CLI to assist debugging
`storybook sandbox --debug` | +| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#how-to-opt-out)
`storybook sandbox --disable-telemetry` | +| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#crash-reports-disabled-by-default)
`storybook sandbox --enable-crash-reports` | diff --git a/docs/configure/styling-and-css.md b/docs/configure/styling-and-css.md index 630e6e25ab7d..63fe7b6c9447 100644 --- a/docs/configure/styling-and-css.md +++ b/docs/configure/styling-and-css.md @@ -37,8 +37,7 @@ However, these files will not be subject to HMR, so you'll need to restart your @@ -138,7 +137,7 @@ To add global styles to your Storybook, you can add them to the `styles` array i Don't forget to also add your global styles to your `build-storybook` target in your `angular.json` file. This will ensure that your global styles are included in the static build of your Storybook as well. ```json - { +{ "storybook": { "builder": "@storybook/angular:start-storybook", "options": { @@ -234,4 +233,3 @@ Starting with version 14.1.8, Nx uses the Storybook builder directly, which mean When Nx runs, it will load Storybook's configuration and styling based on [`storybook.browserTarget`](https://nx.dev/storybook/extra-topics-for-angular-projects#setting-up-browsertarget). - diff --git a/docs/snippets/angular/list-story-reuse-data.ts.mdx b/docs/snippets/angular/list-story-reuse-data.ts.mdx index 3ff20f0d824a..7f531c257527 100644 --- a/docs/snippets/angular/list-story-reuse-data.ts.mdx +++ b/docs/snippets/angular/list-story-reuse-data.ts.mdx @@ -26,11 +26,6 @@ const meta: Meta = { export default meta; type Story = StoryObj; -/* - *๐Ÿ‘‡ Render functions are a framework specific feature to allow you control on how the component renders. - * See https://storybook.js.org/docs/api/csf - * to learn how to use render functions. - */ export const ManyItems: Story = { args: { Selected: Selected.args.isSelected, diff --git a/docs/snippets/common/storybook-preview-head-import-global-styles.html.mdx b/docs/snippets/common/storybook-preview-head-import-global-styles.html.mdx new file mode 100644 index 000000000000..5fc69fa6bad7 --- /dev/null +++ b/docs/snippets/common/storybook-preview-head-import-global-styles.html.mdx @@ -0,0 +1,13 @@ +```html + + + + + + + + +``` diff --git a/docs/snippets/html/button-story-default-exports.js.mdx b/docs/snippets/html/button-story-default-export.js.mdx similarity index 100% rename from docs/snippets/html/button-story-default-exports.js.mdx rename to docs/snippets/html/button-story-default-export.js.mdx diff --git a/docs/snippets/html/button-story-default-exports.ts.mdx b/docs/snippets/html/button-story-default-export.ts.mdx similarity index 100% rename from docs/snippets/html/button-story-default-exports.ts.mdx rename to docs/snippets/html/button-story-default-export.ts.mdx diff --git a/docs/snippets/html/list-story-reuse-data.js.mdx b/docs/snippets/html/list-story-reuse-data.js.mdx index 76a6f8820a3b..fe46d1a44f71 100644 --- a/docs/snippets/html/list-story-reuse-data.js.mdx +++ b/docs/snippets/html/list-story-reuse-data.js.mdx @@ -8,18 +8,9 @@ import { createListItem } from './ListItem'; import { Selected, Unselected } from './ListItem.stories'; export default { - /* ๐Ÿ‘‡ The title prop is optional. - * See https://storybook.js.org/docs/configure/#configure-story-loading - * to learn how to generate automatic titles - */ title: 'List', }; -/* - *๐Ÿ‘‡ Render functions are a framework specific feature to allow you control on how the component renders. - * See https://storybook.js.org/docs/api/csf - * to learn how to use render functions. - */ export const ManyItems = { render: (args) => { const list = createList(args); diff --git a/docs/snippets/html/list-story-reuse-data.ts.mdx b/docs/snippets/html/list-story-reuse-data.ts.mdx index 999a38a65c25..50f984c0bb85 100644 --- a/docs/snippets/html/list-story-reuse-data.ts.mdx +++ b/docs/snippets/html/list-story-reuse-data.ts.mdx @@ -10,21 +10,12 @@ import { createListItem } from './ListItem'; import { Selected, Unselected } from './ListItem.stories'; const meta: Meta = { - /* ๐Ÿ‘‡ The title prop is optional. - * See https://storybook.js.org/docs/configure/#configure-story-loading - * to learn how to generate automatic titles - */ title: 'List', }; export default meta; type Story = StoryObj; -/* - *๐Ÿ‘‡ Render functions are a framework specific feature to allow you control on how the component renders. - * See https://storybook.js.org/docs/api/csf - * to learn how to use render functions. - */ export const ManyItems: Story = { render: (args) => { const list = createList(args); diff --git a/docs/snippets/react/list-story-reuse-data.js.mdx b/docs/snippets/react/list-story-reuse-data.js.mdx index 2e35ca9c2dab..6f99fad942ef 100644 --- a/docs/snippets/react/list-story-reuse-data.js.mdx +++ b/docs/snippets/react/list-story-reuse-data.js.mdx @@ -13,12 +13,6 @@ export default { component: List, }; -/* - *๐Ÿ‘‡ Render functions are a framework specific feature to allow you control on how the component renders. - * See https://storybook.js.org/docs/api/csf - * to learn how to use render functions. - */ - export const ManyItems = { render: (args) => ( diff --git a/docs/snippets/react/list-story-reuse-data.ts-4-9.mdx b/docs/snippets/react/list-story-reuse-data.ts-4-9.mdx index 07767df39468..6fbee90aa76a 100644 --- a/docs/snippets/react/list-story-reuse-data.ts-4-9.mdx +++ b/docs/snippets/react/list-story-reuse-data.ts-4-9.mdx @@ -16,11 +16,6 @@ const meta = { export default meta; type Story = StoryObj; -/* - *๐Ÿ‘‡ Render functions are a framework specific feature to allow you control on how the component renders. - * See https://storybook.js.org/docs/api/csf - * to learn how to use render functions. - */ export const ManyItems: Story = { render: (args) => ( diff --git a/docs/snippets/react/list-story-reuse-data.ts.mdx b/docs/snippets/react/list-story-reuse-data.ts.mdx index 006e28639c99..5e8382162d6a 100644 --- a/docs/snippets/react/list-story-reuse-data.ts.mdx +++ b/docs/snippets/react/list-story-reuse-data.ts.mdx @@ -16,11 +16,6 @@ const meta: Meta = { export default meta; type Story = StoryObj; -/* - *๐Ÿ‘‡ Render functions are a framework specific feature to allow you control on how the component renders. - * See https://storybook.js.org/docs/api/csf - * to learn how to use render functions. - */ export const ManyItems: Story = { render: (args) => ( diff --git a/docs/snippets/solid/list-story-reuse-data.js.mdx b/docs/snippets/solid/list-story-reuse-data.js.mdx index 812843a505e6..e893f403e914 100644 --- a/docs/snippets/solid/list-story-reuse-data.js.mdx +++ b/docs/snippets/solid/list-story-reuse-data.js.mdx @@ -11,12 +11,6 @@ export default { component: List, }; -/* - *๐Ÿ‘‡ Render functions are a framework specific feature to allow you control on how the component renders. - * See https://storybook.js.org/docs/api/csf - * to learn how to use render functions. - */ - export const ManyItems = { render: (args) => ( diff --git a/docs/snippets/solid/list-story-reuse-data.ts-4-9.mdx b/docs/snippets/solid/list-story-reuse-data.ts-4-9.mdx index 5d4e5aae4e28..78e8b4d089fb 100644 --- a/docs/snippets/solid/list-story-reuse-data.ts-4-9.mdx +++ b/docs/snippets/solid/list-story-reuse-data.ts-4-9.mdx @@ -16,11 +16,6 @@ const meta = { export default meta; type Story = StoryObj; -/* - *๐Ÿ‘‡ Render functions are a framework specific feature to allow you control on how the component renders. - * See https://storybook.js.org/docs/api/csf - * to learn how to use render functions. - */ export const ManyItems: Story = { render: (args) => ( diff --git a/docs/snippets/solid/list-story-reuse-data.ts.mdx b/docs/snippets/solid/list-story-reuse-data.ts.mdx index 636f66d6b020..cccd2b421cc8 100644 --- a/docs/snippets/solid/list-story-reuse-data.ts.mdx +++ b/docs/snippets/solid/list-story-reuse-data.ts.mdx @@ -16,11 +16,6 @@ const meta: Meta = { export default meta; type Story = StoryObj; -/* - *๐Ÿ‘‡ Render functions are a framework specific feature to allow you control on how the component renders. - * See https://storybook.js.org/docs/api/csf - * to learn how to use render functions. - */ export const ManyItems: Story = { render: (args) => ( diff --git a/docs/snippets/vue/list-story-reuse-data.3.js.mdx b/docs/snippets/vue/list-story-reuse-data.3.js.mdx index d9384dd001d2..ab3b3f042072 100644 --- a/docs/snippets/vue/list-story-reuse-data.3.js.mdx +++ b/docs/snippets/vue/list-story-reuse-data.3.js.mdx @@ -11,11 +11,6 @@ export default { component: List, }; -/* - *๐Ÿ‘‡ Render functions are a framework specific feature to allow you control on how the component renders. - * See https://storybook.js.org/docs/api/csf - * to learn how to use render functions. - */ export const ManyItems = { render: (args) => ({ components: { List, ListItem }, diff --git a/docs/snippets/vue/list-story-reuse-data.3.ts-4-9.mdx b/docs/snippets/vue/list-story-reuse-data.3.ts-4-9.mdx index 37c83e2a7edc..bfcc9be89175 100644 --- a/docs/snippets/vue/list-story-reuse-data.3.ts-4-9.mdx +++ b/docs/snippets/vue/list-story-reuse-data.3.ts-4-9.mdx @@ -16,11 +16,6 @@ const meta = { export default meta; type Story = StoryObj; -/* - *๐Ÿ‘‡ Render functions are a framework specific feature to allow you control on how the component renders. - * See https://storybook.js.org/docs/api/csf - * to learn how to use render functions. - */ export const ManyItems: Story = { render: (args) => ({ components: { List, ListItem }, diff --git a/docs/snippets/vue/list-story-reuse-data.3.ts.mdx b/docs/snippets/vue/list-story-reuse-data.3.ts.mdx index 99c0bde71faa..93bf88a25d67 100644 --- a/docs/snippets/vue/list-story-reuse-data.3.ts.mdx +++ b/docs/snippets/vue/list-story-reuse-data.3.ts.mdx @@ -16,11 +16,6 @@ const meta: Meta = { export default meta; type Story = StoryObj; -/* - *๐Ÿ‘‡ Render functions are a framework specific feature to allow you control on how the component renders. - * See https://storybook.js.org/docs/api/csf - * to learn how to use render functions. - */ export const ManyItems: Story = { render: (args) => ({ components: { List, ListItem }, diff --git a/docs/snippets/vue/vue3-vite-add-framework.ts.mdx b/docs/snippets/vue/vue3-vite-add-framework.ts.mdx index c02ed2ed0b3b..404f53f5cc47 100644 --- a/docs/snippets/vue/vue3-vite-add-framework.ts.mdx +++ b/docs/snippets/vue/vue3-vite-add-framework.ts.mdx @@ -1,6 +1,6 @@ ```ts // .storybook/main.ts -import { StorybookConfig } from '@storybook/nextjs'; +import { StorybookConfig } from '@storybook/vue3-vite'; const config: StorybookConfig = { // ... diff --git a/docs/versions/latest.json b/docs/versions/latest.json index 34455f2dd966..20186e787b72 100644 --- a/docs/versions/latest.json +++ b/docs/versions/latest.json @@ -1 +1 @@ -{"version":"8.0.5","info":{"plain":"- Addon-docs: Fix `react-dom/server` imports breaking stories and docs - [#26557](https://github.com/storybookjs/storybook/pull/26557), thanks @JReinhold!\n- Automigrations: Fix missing support for mts vite config - [#26441](https://github.com/storybookjs/storybook/pull/26441), thanks @drik98!\n- CLI: Improve Yarn berry error parsing - [#26616](https://github.com/storybookjs/storybook/pull/26616), thanks @yannbf!\n- React-Docgen: Make sure to be able to handle empty unions - [#26639](https://github.com/storybookjs/storybook/pull/26639), thanks @kasperpeulen!\n- Viewport: Fix missing style - [#26530](https://github.com/storybookjs/storybook/pull/26530), thanks @jpzwarte!"}} +{"version":"8.0.6","info":{"plain":"- CLI: Add --config-dir flag to migrate command - [#26721](https://github.com/storybookjs/storybook/pull/26721), thanks @yannbf!\n- Next.js: Fix next/font usage on Windows machines - [#26700](https://github.com/storybookjs/storybook/pull/26700), thanks @valentinpalkovic!\n- Next.js: Support path aliases when no base url is set - [#26651](https://github.com/storybookjs/storybook/pull/26651), thanks @yannbf!\n- Webpack: Fix sourcemap generation in webpack react-docgen-loader - [#26676](https://github.com/storybookjs/storybook/pull/26676), thanks @valentinpalkovic!"}} diff --git a/docs/versions/next.json b/docs/versions/next.json index 5bca2714437b..a2ba413b8e56 100644 --- a/docs/versions/next.json +++ b/docs/versions/next.json @@ -1 +1 @@ -{"version":"8.1.0-alpha.4","info":{"plain":"- Addon Docs: Support Stencil based display names in source snippets - [#26592](https://github.com/storybookjs/storybook/pull/26592), thanks @yannbf!\n- Angular: Add type support for Angular's input signals - [#26413](https://github.com/storybookjs/storybook/pull/26413), thanks @valentinpalkovic!\n- Angular: Add type support for Angular's output signals - [#26546](https://github.com/storybookjs/storybook/pull/26546), thanks @valentinpalkovic!\n- CLI: Instruct the correct auto-migration command - [#26515](https://github.com/storybookjs/storybook/pull/26515), thanks @ndelangen!\n- CLI: Throw an error when running upgrade command in incorrect cwd - [#26585](https://github.com/storybookjs/storybook/pull/26585), thanks @yannbf!\n- CSF: Allow default export without title or component attributes - [#26516](https://github.com/storybookjs/storybook/pull/26516), thanks @kasperpeulen!\n- Core: Fix preloading too early - [#26442](https://github.com/storybookjs/storybook/pull/26442), thanks @ndelangen!\n- UI: Replace the icon prop in the Manager API - [#26477](https://github.com/storybookjs/storybook/pull/26477), thanks @cdedreuille!"}} +{"version":"8.1.0-alpha.6","info":{"plain":"- CLI: Add --config-dir flag to migrate command - [#26721](https://github.com/storybookjs/storybook/pull/26721), thanks @yannbf!\n- Core: Add `duration` and `onClick` support to Notification API and improve Notification UI - [#26696](https://github.com/storybookjs/storybook/pull/26696), thanks @ghengeveld!\n- Dependency: Bump es-module-lexer - [#26737](https://github.com/storybookjs/storybook/pull/26737), thanks @valentinpalkovic!\n- Dependency: Update globby dependency - [#26733](https://github.com/storybookjs/storybook/pull/26733), thanks @valentinpalkovic!\n- Dependency: Update postcss-loader in Next.js framework - [#26707](https://github.com/storybookjs/storybook/pull/26707), thanks @valentinpalkovic!\n- Next.js: Fix next/font usage on Windows machines - [#26700](https://github.com/storybookjs/storybook/pull/26700), thanks @valentinpalkovic!\n- Webpack: Fix sourcemap generation in webpack react-docgen-loader - [#26676](https://github.com/storybookjs/storybook/pull/26676), thanks @valentinpalkovic!"}} diff --git a/docs/writing-stories/index.md b/docs/writing-stories/index.md index abc6632d90f8..ec51a7dc1d39 100644 --- a/docs/writing-stories/index.md +++ b/docs/writing-stories/index.md @@ -357,7 +357,7 @@ Decorators [can be more complex](./decorators.md#context-for-mocking) and are of ## Stories for two or more components -When building design systems or component libraries, you may have two or more components created to work together. For instance, if you have a parent `List` component, it may require child `ListItem` components. +Sometimes you may have two or more components created to work together. For instance, if you have a parent `List` component, it may require child `ListItem` components. @@ -405,7 +405,7 @@ In such cases, it makes sense to render a different function for each story: -You can also reuse stories from the child `ListItem` in your `List` component. Thatโ€™s easier to maintain because you donโ€™t have to keep the identical story definitions updated in multiple places. +You can also reuse _story data_ from the child `ListItem` in your `List` component. Thatโ€™s easier to maintain because you donโ€™t have to update it in multiple places. diff --git a/docs/writing-stories/stories-for-multiple-components.md b/docs/writing-stories/stories-for-multiple-components.md index 708ccce28787..a51a58867445 100644 --- a/docs/writing-stories/stories-for-multiple-components.md +++ b/docs/writing-stories/stories-for-multiple-components.md @@ -2,7 +2,13 @@ title: 'Stories for multiple components' --- -It's useful to write stories that [render two or more components](../writing-stories/index.md#stories-for-two-or-more-components) at once if those components are designed to work together. For example, `ButtonGroups`, `Lists`, and `Page` components. Here's an example with `List` and `ListItem` components: +It's useful to write stories that [render two or more components](./index.md#stories-for-two-or-more-components) at once if those components are designed to work together. For example, `ButtonGroup`, `List`, and `Page` components. + +## Subcomponents + +When the components you're documenting have a parent-child relationship, you can use the `subcomponents` property to document them together. This is especially useful when the child component is not meant to be used on its own, but only as part of the parent component. + +Here's an example with `List` and `ListItem` components: @@ -33,32 +39,36 @@ Subcomponents are only intended for documentation purposes and have some limitat Let's talk about some techniques you can use to mitigate the above, which are especially useful in more complicated situations. -## Reusing subcomponent stories +## Reusing story definitions -The simplest change we can make to the above is to reuse the stories of the `ListItem` in the `List`: +We can also reduce repetition in our stories by reusing story definitions. Here, we can reuse the `ListItem` stories' args in the story for `List`: By rendering the `Unchecked` story with its args, we are able to reuse the input data from the `ListItem` stories in the `List`. + + However, we still arenโ€™t using args to control the `ListItem` stories, which means we cannot change them with controls and we cannot reuse them in other, more complex component stories. ## Using children as an arg @@ -82,19 +92,21 @@ Now that `children` is an arg, we can potentially reuse it in another story. However, there are some caveats when using this approach that you should be aware of. -The `children` `args` as any other arg needs to be JSON serializable. It means that you should: +The `children` arg, just like all args, needs to be JSON serializable. To avoid errors with your Storybook, you should: - Avoid using empty values +- Use [mapping](../essentials/controls.md#dealing-with-complex-values) if you want to adjust the value with [controls](../essentials/controls.md) - Use caution with components that include third party libraries -As they could lead into errors with your Storybook. - We're currently working on improving the overall experience for the children arg and allow you to edit children arg in a control and allow you to use other types of components in the near future. But for now you need to factor in this caveat when you're implementing your stories. + + + ## Creating a Template Component Another option that is more โ€œdataโ€-based is to create a special โ€œstory-generatingโ€ template component: