Merge pull request #17358 from storybookjs/chore_docs_fix_storybook_c…

…onfig_overview Chore: (Docs) Updates Storybook configuration docs for TS and flags.
storybookjs · Feb 11, 2022 · f4af62a · f4af62a
2 parents a3433c1 + 5fe5b45
commit f4af62a
Show file tree

Hide file tree

Showing 4 changed files with 126 additions and 7 deletions.
diff --git 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.
 
 <div class="aside">
  💡 Tip: Customize your default story by referencing it first in the `stories` array.
 </div>
 
+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. <br/> `features: { storyStoreV7: true }`                                                                                     |
+| `buildStoriesJson`    | Generates a `stories.json` file to help story loading with the on demand mode. <br/> `features: { buildStoriesJson: true }` <br/> 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.<br/> `features: { emotionAlias: false }` |
+| `babelModeV7`         | Enables the new [Babel configuration](./babel.md#v7-mode) mode for Storybook. <br/> `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. <br/> `features: { postcss: false }`       |
+| `modernInlineRender`  | Enables Storybook's modern inline rendering mode. <br/> `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:
 
 <!-- prettier-ignore-start -->
 
@@ -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:
 
 <!-- prettier-ignore-start -->
 
@@ -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.
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/storybook-ts-config-babelrc.js.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+### 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.
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/storybook-main-default-setup.ts.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+| 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 <br/> `staticDirs:['../public']` |
+| `addons`              | Sets the list of [addons](/addons) loaded by Storybook <br/> `addons:['@storybook/addon-essentials']`                                                                            |
+| `typescript`          | Configures how Storybook handles [TypeScript files](./typescript.md) <br/> `typescript: { check: false, checkOptions: {} }`                                                      |
+| `framework`           | Configures Storybook based on a set of framework-specific settings <br/> `framework:'@storybook/svelte'`                                                                         |
+| `core`                | Sets Storybook's Webpack configuration <br/> `core:{ builder: 'webpack5'}`                                                                                                       |
+| `features`            | Enables Storybook's additional features <br/>. See table below for a list of available features `features: { storyStoreV7: true }`                                               |
+| `refs`                | Configures [Storybook composition](../sharing/storybook-composition.md) <br/> `refs:{ example: { title: 'ExampleStorybook', url:'https://your-url.com' } }`                      |
+| `logLevel`            | Configures Storybook's logs in the browser terminal. Useful for debugging <br/> `logLevel: 'debug'`                                                                                      |
+| `webpackFinal`        | Customize Storybook's [Webpack](./webpack.md) setup <br/> `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).
+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.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']
-}
-```
+  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
@@ -0,0 +1,40 @@
+```ts
+// .storybook/main.ts
+
+// Imports the Storybook's configuration API
+import type { StorybookConfig } from '@storybook/core-common';
+
+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 = config;
+```
diff --git a/docs/snippets/common/storybook-ts-config-babelrc.js.mdx b/docs/snippets/common/storybook-ts-config-babelrc.js.mdx
@@ -0,0 +1,10 @@
+```js
+// .babelrc
+
+{
+  "presets": [
+    "@babel/preset-env",
+    "@babel/preset-typescript"
+  ]
+}
+```