From 75175a48c233ca2caac5d064a69e5dc29542ad29 Mon Sep 17 00:00:00 2001 From: jonniebigodes Date: Thu, 27 Jan 2022 21:23:33 +0000 Subject: [PATCH 1/3] updates Storybook configuration docs for TS and flags. --- docs/configure/overview.md | 67 +++++++++++++++++-- .../storybook-main-default-setup.js copy.mdx | 18 +++++ .../storybook-main-default-setup.ts.mdx | 20 ++++++ .../common/storybook-ts-config-babelrc.js.mdx | 10 +++ 4 files changed, 111 insertions(+), 4 deletions(-) create mode 100644 docs/snippets/common/storybook-main-default-setup.js copy.mdx create mode 100644 docs/snippets/common/storybook-main-default-setup.ts.mdx create mode 100644 docs/snippets/common/storybook-ts-config-babelrc.js.mdx diff --git a/docs/configure/overview.md b/docs/configure/overview.md index 42a2935cd648..a52b1f09854a 100644 --- a/docs/configure/overview.md +++ b/docs/configure/overview.md @@ -30,11 +30,27 @@ The `main.js` configuration file is a [preset](../addons/addon-types.md) and, as - `addons` - a list of the [addons](/addons) you are using. - `webpackFinal` - custom [webpack configuration](./webpack.md#extending-storybooks-webpack-config). - `babel` - custom [babel configuration](./babel.md). +- `framework` - framework specific configurations to help the loading and building process.
đź’ˇ Tip: Customize your default story by referencing it first in the `stories` array.
+See all the [available](#using-storybook-api) fields below if you need further customization. + +### Feature flags + +Additionally, you can also provide additional feature flags to your Storybook configuration. Below is an abridged list of available features that are currently available. + +| Configuration element | Description | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `storyStoreV7` | Configures Storybook to load stories [on demand](#on-demand-story-loading), rather than during boot up.
`features: { storyStoreV7: true }` | +| `buildStoriesJson` | Generates a `stories.json` file to help story loading with the on demand mode.
`features: { buildStoriesJson: true }`
Requires `storyStoreV7`. | +| `emotionAlias` | Provides backwards compatibility for Emotion. See the [migration documentation](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#emotion11-quasi-compatibility) for context.
`features: { emotionAlias: false }` | +| `babelModeV7` | Enables the new [Babel configuration](./babel.md#v7-mode) mode for Storybook.
`features: { babelModeV7: true }` | +| `postcss` | Disables the implicit PostCSS warning. See the [migration documentation](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#deprecated-implicit-postcss-loader) for context.
`features: { postcss: false }` | +| `modernInlineRender` | Enables Storybook's modern inline rendering mode.
`features: { modernInlineRender: false }` | + ## Configure story loading By default, Storybook will load stories from your project based on a glob (pattern matching string) in `.storybook/main.js` that matches all files in your project with extension `.stories.*`. The intention is you colocate a story file with the component it documents. @@ -46,7 +62,7 @@ By default, Storybook will load stories from your project based on a glob (patte └── Button.stories.js ``` -If you want to use a different naming convention, you can alter the glob, using the syntax supported by [picomatch](https://github.com/micromatch/picomatch#globbing-features). +If you want to use a different naming convention, you can alter the glob using the syntax supported by [picomatch](https://github.com/micromatch/picomatch#globbing-features). For example, if you wanted to pull both `.md` and `.js` files from the `my-project/src/components` directory, you could write: @@ -62,7 +78,7 @@ For example, if you wanted to pull both `.md` and `.js` files from the `my-proje ### With a configuration object -Additionally, you can also customize your Storybook configuration to load your stories based on a configuration object. For example, if you wanted to load your stories from a `packages` directory, you could adjust your `stories` configuration field into the following: +Additionally, you can customize your Storybook configuration to load your stories based on a configuration object. For example, if you wanted to load your stories from a `packages` directory, you could adjust your `stories` configuration field into the following: @@ -92,7 +108,7 @@ You can also simplify your Storybook configuration and load the stories based on ### With a custom implementation -You can also adjust your Storybook configuration and implement your own custom logic for loading your stories. For example, suppose you were working on a project that includes a particular pattern that the conventional ways of loading stories could not solve, in that case, you could adjust your configuration as follows: +You can also adjust your Storybook configuration and implement your custom logic for loading your stories. For example, suppose you were working on a project that includes a particular pattern that the conventional ways of loading stories could not solve, in that case, you could adjust your configuration as follows: @@ -127,6 +143,49 @@ This feature is experimental, and it has some limitations on what you can and ca - [CSF formats](../api/csf.md) from version 1 to version 3 are supported. The `storiesOf` construct is not. - Custom`storySort` functions are allowed based on a restricted API. +## Configure your project with TypeScript + +If you need, you can also configure your Storybook using TypeScript. To get started, add a `.babelrc` file inside your project and include the following Babel presets: + +Rename your `.storybook/main.js` to `.storybook/main.ts` and restart your Storybook. + + + + + + + +### Using Storybook API + +You can also use Storybook's API to configure your project with TypeScript. Under the hood, it mirrors the exact configuration you get by default. Below is an abridged Storybook configuration with TypeScript and additional information about each configuration element. + + + + + + + +| Configuration element | Description | +| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `stories` | The array of globs that indicates the [location of your story files](#configure-story-loading), relative to `main.ts` | +| `staticDirs` | Sets a list of directories of [static files](./images-and-assets.md#serving-static-files-via-storybook-configuration) to be loaded by Storybook
`staticDirs:['../public']` | +| `addons` | Sets the list of [addons](/addons) loaded by Storybook
`addons:['@storybook/addon-essentials']` | +| `typescript` | Configures how Storybook handles [TypeScript files](./typescript.md)
`typescript: { check: false, checkOptions: {} }` | +| `framework` | Configures Storybook based on a set of framework-specific settings
`framework:'@storybook/svelte'` | +| `core` | Sets Storybook's Webpack configuration
`core:{ builder: 'webpack5'}` | +| `features` | Enables Storybook's additional features
. See table below for a list of available features `features: { storyStoreV7: true }` | +| `refs` | Configures [Storybook composition](../sharing/storybook-composition.md)
`refs:{ example: { title: 'ExampleStorybook', url:'https://your-url.com' } }` | +| `logLevel` | Configures Storybook's logs in the terminal. Useful for debugging
`logLevel: 'debug'` | +| `webpackFinal` | Customize Storybook's [Webpack](./webpack.md) setup
`webpackFinal: async (config:any) => { return config; }` | + ## Configure story rendering To control the way stories are rendered and add global [decorators](../writing-stories/decorators.md#global-decorators) and [parameters](../writing-stories/parameters.md#global-parameters), create a `.storybook/preview.js` file. This is loaded in the Canvas tab, the “preview” iframe that renders your components in isolation. Use `preview.js` for global code (such as [CSS imports](../get-started/setup.md#render-component-styles) or JavaScript mocks) that applies to all stories. @@ -143,4 +202,4 @@ If you’re looking to change how to order your stories, read about [sorting sto To control the behavior of Storybook’s UI (the **“manager”**), you can create a `.storybook/manager.js` file. -This file does not have a specific API but is the place to set [UI options](./features-and-behavior.md) and to configure Storybook’s [theme](./theming.md). \ No newline at end of file +This file does not have a specific API but is the place to set [UI options](./features-and-behavior.md) and to configure Storybook’s [theme](./theming.md). diff --git a/docs/snippets/common/storybook-main-default-setup.js copy.mdx b/docs/snippets/common/storybook-main-default-setup.js copy.mdx new file mode 100644 index 000000000000..0e69c590b09c --- /dev/null +++ b/docs/snippets/common/storybook-main-default-setup.js copy.mdx @@ -0,0 +1,18 @@ +```js +// .storybook/main.js + +module.exports = { + addons: ['@storybook/addon-essentials'], + babel: async (options) => ({ + // Update your babel configuration here + ...options, + }), + framework: '@storybook/react', + stories: ['../src/**/*.stories.@(js|mdx)'], + webpackFinal: async (config, { configType }) => { + // Make whatever fine-grained changes you need + // Return the altered config + return config; + }, +}; +``` diff --git a/docs/snippets/common/storybook-main-default-setup.ts.mdx b/docs/snippets/common/storybook-main-default-setup.ts.mdx new file mode 100644 index 000000000000..edc44782a886 --- /dev/null +++ b/docs/snippets/common/storybook-main-default-setup.ts.mdx @@ -0,0 +1,20 @@ +```ts +// .storybook/main.ts + +// Imports the Storybook's configuration API +import type { StorybookConfig } from '@storybook/core-common'; + +const BaseConfig: StorybookConfig = { + stories: [], + staticDirs: [], + addons: [], + typescript: {}, + framework: '', + core: {}, + features: {}, + refs: {}, + logLevel: '', + webpackFinal: async (config) => {}, +}; +module.exports = BaseConfig; +``` diff --git a/docs/snippets/common/storybook-ts-config-babelrc.js.mdx b/docs/snippets/common/storybook-ts-config-babelrc.js.mdx new file mode 100644 index 000000000000..2fbafc24bc57 --- /dev/null +++ b/docs/snippets/common/storybook-ts-config-babelrc.js.mdx @@ -0,0 +1,10 @@ +```js +// .babelrc + +{ + "presets": [ + "@babel/preset-env", + "@babel/preset-typescript" + ] +} +``` From 9c8238bafe60d7863d402025321acc73ca3a6f59 Mon Sep 17 00:00:00 2001 From: jonniebigodes Date: Thu, 27 Jan 2022 21:30:34 +0000 Subject: [PATCH 2/3] Removes copy of file --- .../storybook-main-default-setup.js copy.mdx | 18 ------------------ .../common/storybook-main-default-setup.js.mdx | 16 +++++++++++++--- 2 files changed, 13 insertions(+), 21 deletions(-) delete mode 100644 docs/snippets/common/storybook-main-default-setup.js copy.mdx diff --git a/docs/snippets/common/storybook-main-default-setup.js copy.mdx b/docs/snippets/common/storybook-main-default-setup.js copy.mdx deleted file mode 100644 index 0e69c590b09c..000000000000 --- a/docs/snippets/common/storybook-main-default-setup.js copy.mdx +++ /dev/null @@ -1,18 +0,0 @@ -```js -// .storybook/main.js - -module.exports = { - addons: ['@storybook/addon-essentials'], - babel: async (options) => ({ - // Update your babel configuration here - ...options, - }), - framework: '@storybook/react', - stories: ['../src/**/*.stories.@(js|mdx)'], - webpackFinal: async (config, { configType }) => { - // Make whatever fine-grained changes you need - // Return the altered config - return config; - }, -}; -``` diff --git a/docs/snippets/common/storybook-main-default-setup.js.mdx b/docs/snippets/common/storybook-main-default-setup.js.mdx index 9b5d877884ae..0e69c590b09c 100644 --- a/docs/snippets/common/storybook-main-default-setup.js.mdx +++ b/docs/snippets/common/storybook-main-default-setup.js.mdx @@ -2,7 +2,17 @@ // .storybook/main.js module.exports = { + addons: ['@storybook/addon-essentials'], + babel: async (options) => ({ + // Update your babel configuration here + ...options, + }), + framework: '@storybook/react', stories: ['../src/**/*.stories.@(js|mdx)'], - addons: ['@storybook/addon-essentials'] -} -``` \ No newline at end of file + webpackFinal: async (config, { configType }) => { + // Make whatever fine-grained changes you need + // Return the altered config + return config; + }, +}; +``` From 5fe5b45fe71a2c99d2066478474a8b48b9ef3fbb Mon Sep 17 00:00:00 2001 From: jonniebigodes Date: Mon, 7 Feb 2022 20:16:13 +0000 Subject: [PATCH 3/3] snippet adjustments per feedback --- docs/configure/overview.md | 2 +- .../storybook-main-default-setup.ts.mdx | 46 +++++++++++++------ 2 files changed, 34 insertions(+), 14 deletions(-) diff --git a/docs/configure/overview.md b/docs/configure/overview.md index a52b1f09854a..38342920067a 100644 --- a/docs/configure/overview.md +++ b/docs/configure/overview.md @@ -183,7 +183,7 @@ You can also use Storybook's API to configure your project with TypeScript. Unde | `core` | Sets Storybook's Webpack configuration
`core:{ builder: 'webpack5'}` | | `features` | Enables Storybook's additional features
. See table below for a list of available features `features: { storyStoreV7: true }` | | `refs` | Configures [Storybook composition](../sharing/storybook-composition.md)
`refs:{ example: { title: 'ExampleStorybook', url:'https://your-url.com' } }` | -| `logLevel` | Configures Storybook's logs in the terminal. Useful for debugging
`logLevel: 'debug'` | +| `logLevel` | Configures Storybook's logs in the browser terminal. Useful for debugging
`logLevel: 'debug'` | | `webpackFinal` | Customize Storybook's [Webpack](./webpack.md) setup
`webpackFinal: async (config:any) => { return config; }` | ## Configure story rendering diff --git a/docs/snippets/common/storybook-main-default-setup.ts.mdx b/docs/snippets/common/storybook-main-default-setup.ts.mdx index edc44782a886..9cad2ee423a4 100644 --- a/docs/snippets/common/storybook-main-default-setup.ts.mdx +++ b/docs/snippets/common/storybook-main-default-setup.ts.mdx @@ -4,17 +4,37 @@ // Imports the Storybook's configuration API import type { StorybookConfig } from '@storybook/core-common'; -const BaseConfig: StorybookConfig = { - stories: [], - staticDirs: [], - addons: [], - typescript: {}, - framework: '', - core: {}, - features: {}, - refs: {}, - logLevel: '', - webpackFinal: async (config) => {}, +const config: StorybookConfig = { + stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'], + staticDirs: ['../public'], + addons: [ + '@storybook/addon-links', + '@storybook/addon-essentials', + '@storybook/preset-create-react-app', + '@storybook/addon-interactions', + ], + typescript: { + check: false, + checkOptions: {}, + reactDocgen: 'react-docgen-typescript', + reactDocgenTypescriptOptions: { + shouldExtractLiteralValuesFromEnum: true, + propFilter: (prop) => (prop.parent ? !/node_modules/.test(prop.parent.fileName) : true), + }, + }, + framework: '@storybook/react', + core: { + builder: 'webpack4', + }, + features: { + postcss: false, + }, + refs: { + 'design-system': { + title: 'Storybook Design System', + url: 'https://5ccbc373887ca40020446347-yldsqjoxzb.chromatic.com', + }, + }, }; -module.exports = BaseConfig; -``` +module.exports = config; +``` \ No newline at end of file