Core: Document main.js config (#9552)

Core: Document main.js config

addons/docs/README.md

@@ -4,6 +4,8 @@
 
 # Storybook Docs
 
+> migration guide: This page documents the method to configure storybook introduced recently in 5.3.0, consult the [migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md) if you want to migrate to this format of configuring storybook.
+
 Storybook Docs transforms your Storybook stories into world-class component documentation.
 
 **DocsPage.** Out of the box, all your stories get a `DocsPage`. `DocsPage` is a zero-config aggregation of your component stories, text descriptions, docgen comments, props tables, and code examples into clean, readable pages.

addons/docs/angular/README.md

@@ -4,6 +4,8 @@
 
 # Storybook Docs for Angular
 
+> migration guide: This page documents the method to configure storybook introduced recently in 5.3.0, consult the [migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md) if you want to migrate to this format of configuring storybook.
+
 Storybook Docs transforms your Storybook stories into world-class component documentation. Storybook Docs for Angular supports [DocsPage](../docs/docspage.md) for auto-generated docs, and [MDX](../docs/mdx.md) for rich long-form docs.
 
 To learn more about Storybook Docs, read the [general documentation](../README.md). To learn the Angular specifics, read on!

addons/docs/ember/README.md

@@ -1,5 +1,7 @@
 # Storybook Docs for Ember
 
+> migration guide: This page documents the method to configure storybook introduced recently in 5.3.0, consult the [migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md) if you want to migrate to this format of configuring storybook.
+
 Storybook Docs transforms your Storybook stories into world-class component documentation. Storybook Docs for Ember supports [DocsPage](../docs/docspage.md) for auto-generated docs, and [MDX](../docs/mdx.md) for rich long-form docs.
 
 To learn more about Storybook Docs, read the [general documentation](../README.md). To learn the Ember specifics, read on!

addons/docs/react/README.md

@@ -4,6 +4,8 @@
 
 # Storybook Docs for React
 
+> migration guide: This page documents the method to configure storybook introduced recently in 5.3.0, consult the [migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md) if you want to migrate to this format of configuring storybook.
+
 Storybook Docs transforms your Storybook stories into world-class component documentation. Storybook Docs for React supports [DocsPage](../docs/docspage.md) for auto-generated docs, and [MDX](../docs/mdx.md) for rich long-form docs.
 
 To learn more about Storybook Docs, read the [general documentation](../README.md). To learn the React specifics, read on!

addons/docs/vue/README.md

@@ -4,6 +4,8 @@
 
 # Storybook Docs for Vue
 
+> migration guide: This page documents the method to configure storybook introduced recently in 5.3.0, consult the [migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md) if you want to migrate to this format of configuring storybook.
+
 Storybook Docs transforms your Storybook stories into world-class component documentation. Storybook Docs for Vue supports [DocsPage](../docs/docspage.md) for auto-generated docs, and [MDX](../docs/mdx.md) for rich long-form docs.
 
 To learn more about Storybook Docs, read the [general documentation](../README.md). To learn the Vue specifics, read on!

docs/gatsby-config.js

@@ -28,6 +28,7 @@ module.exports = {
         '/guides/guide-svelte/',
       ],
       configurations: [
+        '/configurations/overview/',
         '/configurations/options-parameter/',
         '/configurations/default-config/',
         '/configurations/custom-webpack-config/',

docs/src/pages/addons/using-addons/index.md

@@ -3,6 +3,8 @@ id: 'using-addons'
 title: 'Using Addons'
 ---
 
+> migration guide: This page documents the method to configure storybook introduced recently in 5.3.0, consult the [migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md) if you want to migrate to this format of configuring storybook.
+
 Storybook comes with a variety of "core" addons developed and maintained alongside Storybook. Most examples in this site use [actions](https://github.com/storybookjs/storybook/tree/master/addons/actions) and [links](https://github.com/storybookjs/storybook/tree/master/addons/links). But you can use any third party addons distributed via NPM.
 
 Here's how to do it.

docs/src/pages/addons/writing-addons/index.md

@@ -3,6 +3,8 @@ id: 'writing-addons'
 title: 'Writing Addons'
 ---
 
+> migration guide: This page documents the method to configure storybook introduced recently in 5.3.0, consult the [migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md) if you want to migrate to this format of configuring storybook.
+
 This is a complete guide on how to create addons for Storybook.
 
 ## Storybook Basics

docs/src/pages/basics/writing-stories/index.md

@@ -3,6 +3,8 @@ id: 'writing-stories'
 title: 'Writing Stories'
 ---
 
+> migration guide: This page documents the method to configure storybook introduced recently in 5.3.0, consult the [migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md) if you want to migrate to this format of configuring storybook.
+
 A Storybook is a collection of stories. Each story represents a single visual state of a component.
 
 > Technically, a story is a function that returns something that can be rendered to screen.

docs/src/pages/configurations/custom-webpack-config/index.md

@@ -3,6 +3,8 @@ id: 'custom-webpack-config'
 title: 'Custom Webpack Config'
 ---
 
+> migration guide: This page documents the method to configure storybook introduced recently in 5.3.0, consult the [migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md) if you want to migrate to this format of configuring storybook.
+
 You can customize Storybook's webpack setup by providing a `webpack` field in `main.js` file.
 The value should be an async function that receives a webpack config and eventually returns a webpack config.
 

docs/src/pages/configurations/overview/index.md

@@ -0,0 +1,81 @@
+
+---
+id: 'overview'
+title: 'Configuration overview'
+---
+
+For CLI options see: [here](/docs/cli-options).
+
+> migration guide: This page documents the method to configure storybook introduced recently in 5.3.0, consult the [migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md) if you want to migrate to this format of configuring storybook.
+
+## main configuration
+
+Storybook has a few files it uses for configuration, and they are grouped together into a directory (default: `.storybook`).
+
+The most import file is the `main.js` file. This is where general config is declared.
+
+Here's an minimal example of a that file:
+
+```js
+module.exports = {
+  stories: ['../src/components/**/*.stories.js'],
+  addons: [
+    '@storybook/addon-essentials',
+  ],
+};
+```
+
+The addons field can refer to traditional [addons](docs/addons/introduction), but it can also include [presets](/docs/presets/introduction/) extending the config further.
+
+## manager & preview
+
+Storybook works by being split into 2 applications, which communicate with each other over a postmessage channel; called the "manager" and "preview".
+
+The preview application is essentially just your stories with a framework agnostic 'router'. Making it so when the manager application tells it so, it renders the correct story.
+
+The manager application renders the UI of [addons](docs/addons/introduction), the navigator and [toolbar](/docs/basics/toolbar-guide/).
+
+There are 2 extra config files, for doing some special runtime configs for each of those 2 applications.
+
+In `preview.js` you can add global [decorators](../../basics/writing-stories/#decorators) and [parameters](../../basics/writing-stories/#parameters):
+
+```js
+// preview.js
+import { addDecorator } from '@storybook/svelte';
+import { withA11y } from '@storybook/addon-a11y';
+
+addDecorator(withA11y);
+```
+
+In `manager.js` you can add [UI options](/docs/configurations/options-parameter/#global-options).
+
+```js
+// manager.js
+import { themes } from '@storybook/theming/create';
+import { addons } from '@storybook/addons';
+
+addons.setConfig({
+  theme: themes.dark,
+});
+```
+
+## entire main.js config
+
+The `main.js` file is actually a preset! so if you know how to configure storybook, you know how to write a preset, and vice-versa!
+So the API of `main.js` is equal to [that of presets](/docs/presets/writing-presets/#presets-api).
+
+Here's an overview of the important configuration properties in `main.js`:
+
+```js
+module.exports = {
+  // and array of glob patterns
+  stories: ['../src/components/**/*.stories.js'],
+
+  // an array of addons & presets
+  addons: ['@storybook/addon-essentials'],
+};
+```
+
+## webpack
+
+For how to customize webpack, [view the customize webpack section](/docs/configurations/custom-webpack-config/)

docs/src/pages/configurations/typescript-config/index.md

@@ -3,6 +3,8 @@ id: 'typescript-config'
 title: 'TypeScript Config'
 ---
 
+> migration guide: This page documents the method to configure storybook introduced recently in 5.3.0, consult the [migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md) if you want to migrate to this format of configuring storybook.
+
 This is a central reference for using Storybook with TypeScript.
 
 ## Typescript configuration presets

docs/src/pages/presets/introduction/index.md

@@ -3,6 +3,8 @@ id: 'introduction'
 title: 'Intro to Presets'
 ---
 
+> migration guide: This page documents the method to configure storybook introduced recently in 5.3.0, consult the [migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md) if you want to migrate to this format of configuring storybook.
+
 Storybook **presets** are grouped collections of `babel`, `webpack`, and `addons` configurations that support specific use cases.
 
 For example, to write your stories in Typescript, rather than [manually configuring Storybook for typescript](../../configurations/typescript-config/) with individual [babel](../../configurations/custom-babel-config/) and [webpack](../../configurations/custom-webpack-config/) configs, you can use the `@storybook/preset-typescript` package, which does the heavy lifting for you.

docs/src/pages/presets/writing-presets/index.md

@@ -3,6 +3,8 @@ id: 'writing-presets'
 title: 'Writing Presets'
 ---
 
+> migration guide: This page documents the method to configure storybook introduced recently in 5.3.0, consult the [migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md) if you want to migrate to this format of configuring storybook.
+
 [Storybook presets](../introduction/) are grouped collections of `babel`, `webpack`, and `addons` configurations that support specific use cases in Storybook, such as typescript or MDX support.
 
 This doc covers the [presets API](#presets-api) and how to use the presets mechanism for [advanced configuration](#advanced-configuration).
@@ -99,6 +101,33 @@ module.exports = {
 };
 ```
 
+### Addons
+
+For users, the name `managerEntries` might be a bit too technical, so instead both users and preset-authors can simply use the property: `addons`:
+
+```js
+module.exports = {
+  addons: ['@storybook/addon-storysource/register'],
+};
+```
+
+The array of values can support both references to other presets and addons that should be included into the manager.
+
+Storybook will automatically detect whether a reference to an addon is a preset or a manager entry by checking if the package contains a `./preset.js` or `./register.js` (manager entry), falling back to preset if it is unsure.
+
+If this heuristic is incorrect for an addon you are using, you can explicitly opt in to an entry being an a manager entry using the `managerEntries` key.
+
+Here's what it looks when combining presets and managerEntries in the addons property:
+
+```js
+module.exports = {
+  addons: [
+    '@storybook/addon-storysource/register', // a managerEntry
+    '@storybook/addon-docs/preset', // a preset
+  ],
+};
+```
+
 ### Entries
 
 Entries are the place to register entry points for the preview. For example it could be used to make a basic configure-storybook preset that loads all the `*.stories.js` files into SB, instead of forcing people to copy-paste the same thing everywhere.
@@ -128,7 +157,6 @@ module.exports = {
   babel: async (config, options) => {
     return config;
   },
-  addons: [],
 };
 ```
 
@@ -140,7 +168,7 @@ Change your `main.js` file to:
 const path = require('path');
 
 module.exports = {
-  presets: [path.resolve('./.storybook/my-preset')],
+  addons: [path.resolve('./.storybook/my-preset')],
 };
 ```
 
@@ -162,7 +190,6 @@ module.exports = {
   babel: async (config, options) => {
     return config;
   },
-  addons: [],
 };
 ```