Merge pull request #18970 from storybookjs/chore_docs_composition_upd…

…ates

Chore: (Docs) Minor tweaks to the composition docs

docs/sharing/storybook-composition.md

@@ -30,12 +30,12 @@ In your [`.storybook/main.js`](../configure/overview.md#configure-story-renderin
 <!-- prettier-ignore-end -->
 
 <div class="aside">
- 💡 Limitation: Addons in composed Storybooks will not work as they normally do in non-composed Storybook.
+ 💡 Limitation: Addons in composed Storybooks will not work as they normally do in a non-composed Storybook.
 </div>
 
 ## Compose local Storybooks
 
-You can also compose multiple Storybooks that are running locally. For instance, if you have a React Storybook and a Angular Storybook running on different ports you can update your configuration file (i.e., `.storybook/main.js`) and reference them;
+You can also compose multiple Storybooks that are running locally. For instance, if you have a React Storybook and an Angular Storybook running on different ports, you can update your configuration file (i.e., `.storybook/main.js`) and reference them;
 
 <!-- prettier-ignore-start -->
 
@@ -47,11 +47,11 @@ You can also compose multiple Storybooks that are running locally. For instance,
 
 <!-- prettier-ignore-end -->
 
-Adding this configuration will combine both the React and Angular Storybooks into your current one. When either of these changes, you’ll see the changes being applied automatically. Enabling you to develop both frameworks in sync.
+Adding this configuration will combine React and Angular Storybooks into your current one. You’ll see the changes being applied automatically when either of these changes. Enabling you to develop both frameworks in sync.
 
 ## Compose Storybooks per environment
 
-You can also compose Storybooks based on the current development environment (e.g, development, staging, production). For instance if the project you're working on has already a published Storybook, but also includes a version with cutting edge features not yet released you can adjust the composition based on that. For example:
+You can also compose Storybooks based on the current development environment (e.g., development, staging, production). For instance, if the project you're working on already has a published Storybook but also includes a version with cutting-edge features not yet released, you can adjust the composition based on that. For example:
 
 <!-- prettier-ignore-start -->
 
@@ -69,21 +69,57 @@ You can also compose Storybooks based on the current development environment (e.
 
 </div>
 
-### Improve your Storybook composition
+## Improve your Storybook composition
 
-So far we've seen how we can use composition with local or published Storybooks. One thing worth mentioning as your Storybook will grow in time with your own stories, or through composition with other Storybooks, is that you can optimize the deployment process by including the following command in your workflow, run from your project root:
+So far, we've seen how we can use composition with local or published Storybooks. As your Storybook will grow in time with your stories or through composition with other Storybooks, you can optimize the deployment process using various methods.
+
+### With feature flags
+
+If you're using Storybook 6.4, or higher, you can optimize your composition via the `buildStoriesJson` feature flag, allowing you to generate a `stories.json` file with the required information, providing you with a seamless integration without the need for additional dependencies. For example:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/storybook-enable-buildstoriesjson.js.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+<div class="aside">
+
+💡 If you already enabled automatic code splitting via the [`storyStoreV7`](https://storybook.js.org/docs/react/builders/webpack#code-splitting), you won't need this flag as it will automatically generate the `stories.json` file.
+
+</div>
+
+When you compose a Storybook featuring this flag, it will use the information retrieved from the file to populate the UI with your composed Storybook stories automatically. Here's an example of the output generated by the `stories.json` file:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/storybook-storiesjsonflag-result.json.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+### With the CLI
+
+If you're working with an outdated Storybook version or have a project-specific requirement that prevents you from enabling the `buildStoriesJson` feature flag. In that case, you can use Storybook's CLI to automatically generate the `stories.json` file when you deploy your Storybook. For example:
 
 ```shell
 npx storybook extract
 ```
 
 <div class="aside">
 
-`storybook extract` uses [Puppeteer](https://www.npmjs.com/package/puppeteer), which downloads and installs Chromium. Set the environment `SB_CHROMIUM_PATH` to configure your local Chromium installation.
+💡 `storybook extract` uses [Puppeteer](https://www.npmjs.com/package/puppeteer), which downloads and installs Chromium. Set the environment `SB_CHROMIUM_PATH` to configure your local Chromium installation.
 
 </div>
 
-Running this command will generate a `stories.json` file in the default build directory (`storybook-static`) with the information related to your Storybook. Here’s an example of the file contents:
+Although a good approach to improve composition, it comes with a cost, as it will require an additional dependency being added and increased build times. Once it finishes executing, it will generate a `stories.json` file in the default build directory (`storybook-static`) with the information related to your Storybook. Here’s an example of the file contents:
 
 <!-- prettier-ignore-start -->
 
@@ -97,16 +133,16 @@ Running this command will generate a `stories.json` file in the default build di
 
 Linking to a Storybook deployed using this approach will yield all the stories and other relevant information displayed in the UI.
 
-If you need, you can also add additional arguments to this command. For instance, if you want to generate the stories.json file into a custom directory you can use the following:
+If you need, you can also add additional arguments to this command. For instance, if you want to generate the stories.json file into a custom directory, you can use the following:
 
 ```shell
 npx storybook extract my-built-storybook-directory my-other-directory/stories.json
 ```
 
-When executed it will lookup a built Storybook in the `my-built-storybook-directory` and create the `stories.json` file in the `my-other-directory` with all the necessary information.
+When executed, it will look up a built Storybook in the `my-built-storybook-directory` and create the `stories.json` file in the `my-other-directory` with all the necessary information.
 
 <div class="aside">
 
-💡 If you need to use the arguments, you’ll need to include both of them or the command will fail.
+💡 If you need to use the arguments, you’ll need to include both of them, or the command will fail.
 
 </div>

docs/snippets/common/storybook-enable-buildstoriesjson.js.mdx

@@ -0,0 +1,13 @@
+```js
+// .storybook/main.js
+
+module.exports = {
+  stories: [],
+  addons: [
+    // Other Storybook addons
+  ],
+  features: {
+    buildStoriesJson: true, // 👈 Enable this to build the stories.json file
+  },
+};
+```

docs/snippets/common/storybook-storiesjsonflag-result.json.mdx

@@ -0,0 +1,33 @@
+```json
+{
+  "v": 3,
+  "stories": {
+    "components-mycomponent--simple": {
+      "id": "components-mycomponent--simple",
+      "title": "Components/MyComponent",
+      "name": "Simple",
+      "importPath": "./src/components/MyComponent.stories.jsx",
+      "kind": "Components/MyComponent",
+      "story": "Simple",
+      "parameters": {
+        "__id": "components-mycomponent--simple",
+        "docsOnly": false,
+        "fileName": "./src/components/MyComponent.stories.jsx"
+      }
+    },
+    "components-myothercomponent--simple": {
+      "id": "components-myothercomponent--simple",
+      "title": "Components/MyOtherComponent",
+      "name": "Simple",
+      "importPath": "./src/components/MyOtherComponent.stories.jsx",
+      "kind": "Example/Button",
+      "story": "Simple",
+      "parameters": {
+        "__id": "components-myothercomponent--simple",
+        "docsOnly": false,
+        "fileName": "./src/components/MyOtherComponent.stories.jsx"
+      }
+    }
+  }
+}
+```