-Learn more about writing your own preset addon here.
-
+## Learn more about the Storybook addon ecosystem
+
+- Types of addons for other types of addons
+- [Writing addons](./writing-addons.md) for the basics of addon development
+- [Presets](./writing-presets.md) for preset development
+- [Integration catalog](./integration-catalog.md) for requirements and available recipes
+- [API reference](./addons-api.md) to learn about the available APIs
diff --git a/docs/addons/addons-api.md b/docs/addons/addons-api.md
index 8208bf0f7c2c..787bcbe4fdd8 100644
--- a/docs/addons/addons-api.md
+++ b/docs/addons/addons-api.md
@@ -374,3 +374,11 @@ Hook that allows you to retrieve or update a story's [`args`](../writing-stories
/>
+
+## Learn more about the Storybook addon ecosystem
+
+- [Types of addons](./addon-types.md) for other types of addons
+- [Writing addons](./writing-addons.md) for the basics of addon development
+- [Presets](./writing-presets.md) for preset development
+- [Integration catalog](./integration-catalog.md) for requirements and available recipes
+- API reference to learn about the available APIs
diff --git a/docs/addons/github-secrets-screen.png b/docs/addons/github-secrets-screen.png
new file mode 100644
index 000000000000..657049ae3e08
Binary files /dev/null and b/docs/addons/github-secrets-screen.png differ
diff --git a/docs/addons/integration-catalog.md b/docs/addons/integration-catalog.md
index 00fd10fcd84f..e2d1215c0a93 100644
--- a/docs/addons/integration-catalog.md
+++ b/docs/addons/integration-catalog.md
@@ -101,3 +101,11 @@ Not finding the recipe that you want? If it's popular in the community, our docs
### Request a recipe
If you'd like to request a recipe, head over to the [#maintenance channel](https://discord.com/channels/486522875931656193/490070912448724992) of our community Discord and ask.
+
+## Learn more about the Storybook addon ecosystem
+
+- [Types of addons](./addon-types.md) for other types of addons
+- [Writing addons](./writing-addons.md) for the basics of addon development
+- [Presets](./writing-presets.md) for preset development
+- Integration catalog for requirements and available recipes
+- [API reference](./addons-api.md) to learn about the available APIs
diff --git a/docs/addons/storybook-addon-finished-state.mp4 b/docs/addons/storybook-addon-finished-state.mp4
new file mode 100644
index 000000000000..98a740e672d0
Binary files /dev/null and b/docs/addons/storybook-addon-finished-state.mp4 differ
diff --git a/docs/addons/storybook-addon-initial-state.png b/docs/addons/storybook-addon-initial-state.png
new file mode 100644
index 000000000000..76947325fbc9
Binary files /dev/null and b/docs/addons/storybook-addon-initial-state.png differ
diff --git a/docs/addons/writing-addons.md b/docs/addons/writing-addons.md
index f3b1c0b18934..db951af33832 100644
--- a/docs/addons/writing-addons.md
+++ b/docs/addons/writing-addons.md
@@ -2,264 +2,341 @@
title: 'Write an addon'
---
-One of Storybook's main features is its robust addon ecosystem. Use addons to enhance and extend your development workflow. This page shows you how to create your own addon.
+Storybook addons are a powerful way to extend Storybook's functionality and customize the development experience. They can be used to add new features, customize the UI, or integrate with third-party tools.
-## What we're building
+## What are we going to build?
-For this example, we're going to build a bare-bones addon that:
+This reference guide is to help you develop a mental model for how Storybook addons work by building a simple addon based on the popular [Outline addon](https://storybook.js.org/addons/@storybook/addon-outline/). Throughout this guide, you'll learn how addons are structured, Storybook's APIs, how to test your addon locally, and how to publish it.
-- Adds a new panel in Storybook.
-- Retrieves a custom parameter from the stories.
-- Displays the parameter data in the panel.
-
-### Addon kit
-
-This guide shows you how to setup an addon from scratch. Alternatively, you can jumpstart your addon development with the [`addon-kit`](https://github.com/storybookjs/addon-kit).
-
-### Addon directory structure
+
-We recommend a common addon file and directory structure for consistency.
+## Addon anatomy
-| Files/Directories | Description |
-| :---------------- | :--------------------------------- |
-| dist | Transpiled directory for the addon |
-| src | Source code for the addon |
-| .babelrc.js | Babel configuration |
-| preset.js | Addon entry point |
-| package.json | Addon metadata information |
-| README.md | General information for the addon |
+There are two main categories of addons, each with its role:
-### Get started
+- **UI-based**: These addons are responsible for customizing the interface, enabling shortcuts for common tasks, or displaying additional information in the UI.
+- **Presets**: [These](./writing-presets.md) are pre-configured settings or configurations that enable developers to quickly set up and customize their environment with a specific set of features, functionality, or technology.
-Open a new terminal and create a new directory called `my-addon`. Inside it, run `npm init` to initialize a new node project. For your project's name, choose `my-addon` and for entry point `dist/preset.js`.
+### UI-based addons
-Once you've gone through the prompts, your `package.json` should look like:
-
-```json
-{
- "name": "my-addon",
- "version": "1.0.0",
- "description": "A barebones Storybook addon",
- "main": "dist/preset.js",
- "files": ["dist/**/*", "README.md", "*.js"],
- "keywords": ["storybook", "addons"],
- "author": "YourUsername",
- "license": "MIT"
-}
-```
-
-### Build system
-
-We'll need to add the necessary dependencies and make some adjustments. Run the following command to install the required dependencies:
+The addon built in this guide is a UI-based addon, specifically a [toolbar](./addon-types.md#toolbars) addon, enabling users to draw outlines around each element in the story through a shortcut or click of a button. UI addons can create other types of UI elements, each with its function: [panels](./addon-types.md#panels) and [tabs](./addon-types.md#tabs), providing users with various ways to interact with the UI.
-Initialize a local Storybook instance to allow you to test your addon.
+## Setup
-```shell
-npx storybook@latest init
-```
+To create your first addon, you're going to use the [Addon Kit](https://github.com/storybookjs/addon-kit), a ready-to-use template featuring all the required building blocks, dependencies and configurations to help you get started building your addon. In the Addon Kit repository, click the **Use this template** button to create a new repository based on the Addon Kit's code.
-
-💡 Initializing Storybook adds the building blocks for our addon. If you're building a standalone Storybook addon, set the React and Storybook packages as peer dependencies. It prevents the addon from breaking Storybook when there are different versions available.
-
+
-Next, create a `.babelrc.js` file in the root directory with the following:
+Clone the repository you just created and install its dependencies. When the installation process finishes, you will be prompted with questions to configure your addon. Answer them, and when you're ready to start building your addon, run the following command to start Storybook in development mode and develop your addon in watch mode:
-Babel configuration is required because our addon uses ES6 and JSX.
-
-Change your `package.json` and add the following script to build the addon:
-
-```json
-{
- "scripts": {
- "build": "babel ./src --out-dir ./dist"
- }
-}
-```
+ℹ️ The Addon Kit uses [Typescript](https://www.typescriptlang.org/) by default. If you want to use JavaScript instead, you can run the `eject-ts` command to convert the project to JavaScript.
-
-💡 Running yarn build at this stage will output the code into the dist directory, transpiled into a ES5 module ready to be installed into any Storybook.
-Finally, create a new directory called `src` and inside a new file called `preset.js` with the following:
+### Understanding the build system
+
+Addons built in the Storybook ecosystem rely on [tsup](https://tsup.egoist.dev/), a fast, zero-config bundler powered by [esbuild](https://esbuild.github.io/) to transpile your addon's code into modern JavaScript that can run in the browser. Out of the box, the Addon Kit comes with a pre-configured `tsup` configuration file that you can use to customize the build process of your addon.
-Presets are the way addons hook into Storybook. Among other tasks they allow you to:
-
-- Add to [Storybook's UI](#add-a-panel)
-- Add to the [preview iframe](./writing-presets.md#preview-entries)
-- Modify [babel](./writing-presets.md#babel) and [webpack settings](./writing-presets.md#webpack)
+When the build scripts run, it will look for the configuration file and pre-bundle the addon's code based on the configuration provided. However, there are a few properties that are worth referencing:
-For this example, we'll modify Storybook's UI.
+- **entry**: Configures the files to be processed by the bundler. It can be extended to include additional files using a regex pattern.
+- **format**: Enables the generation of multiple output formats. In this case, we're generating a CommonJS and an ES Module version of our addon.
+- **dts**: Auto-generates type definitions for our addon.
+- **platform**: Specifies the target platform for our addon. In this case, we're targeting the browser. It can be set to `node` for Node.js environments or `neutral` for universal modules.
-### Add a panel
+## Register the addon
-Now let’s add a panel to Storybook. Inside the `src` directory, create a new file called `manager.js` and add the following:
+By default, code for the UI-based addons is located in one of the following files, depending on the type of addon built: **`src/Tool.tsx`**, **`src/Panel.tsx`**, or **`src/Tab.tsx`**. Since we're building a toolbar addon, we can safely remove the `Panel` and `Tab` files and update the remaining file to the following:
-
-💡 Make sure to include the key when you register the addon. It will prevent any issues when the addon renders.
-
+Going through the code blocks in sequence:
+
+```ts
+import { useGlobals, useStorybookApi } from '@storybook/manager-api';
-Going over the code snippet in more detail. When Storybook starts up:
+import { Icons, IconButton } from '@storybook/components';
+```
-1. It [registers](./addons-api.md#addonsregister) the addon
-2. [Adds](./addons-api.md#addonsadd) a new `panel` titled `My Addon` to the UI
-3. When selected, the `panel` renders the static `div` content
+The [`useGlobals`](./addons-api.md#useglobals) and [`useStorybookApi`](./addons-api.md#usestorybookapi) hooks from the `manager-api` package are used to access the Storybook's APIs, allowing users to interact with the addon, such as enabling or disabling it. The `Icons` and `IconButtons` components from the [`@storybook/components`](https://www.npmjs.com/package/@storybook/components) package render the icons and buttons in the toolbar.
+
+```ts
+export const Tool = memo(function MyAddonSelector() {
+ const [globals, updateGlobals] = useGlobals();
+ const api = useStorybookApi();
+
+ const isActive = [true, 'true'].includes(globals[PARAM_KEY]);
+
+ const toggleMyTool = useCallback(() => {
+ updateGlobals({
+ [PARAM_KEY]: !isActive,
+ });
+ }, [isActive]);
+
+ useEffect(() => {
+ api.setAddonShortcut(ADDON_ID, {
+ label: 'Toggle Addon [8]',
+ defaultShortcut: ['8'],
+ actionName: 'myaddon',
+ showInMenu: false,
+ action: toggleMyTool,
+ });
+ }, [toggleMyTool, api]);
+
+ return (
+
+
+
+ );
+});
+```
-### Register the addon
+The `Tool` component is the entry point of the addon. It renders the UI elements in the toolbar, registers a keyboard shortcut, and handles the logic to enable and disable the addon.
-Finally, let’s hook it all up. Change `.storybook/main.js` to the following:
+Moving onto the manager, here we register the addon with Storybook using a unique name and identifier. Since we've removed the `Panel` and `Tab` files, we'll need to adjust the file to only reference the addon we're building.
-
-💡 When you register a Storybook addon, it will look for either register.js or preset.js as the entry points.
-
+Notice the `match` property. It allows you to control the view mode where the addon is visible. If you only want to show it in a single mode, you must adjust the property to match the specific mode you aim for. In this case, it will be available in both story and documentation.
-Run `yarn storybook` and you should see something similar to:
+Run the `start` script to build and start Storybook and verify that the addon is registered correctly and showing in the UI.
-
+
-### Display story parameter
+### Style the addon
-Next, let’s replace the `MyPanel` component from above to show the parameter.
+In Storybook, applying styles for addons is considered a side-effect. Therefore, we'll need to make some changes to our addon to allow it to use the styles when it is active and remove them when it's disabled. We're going to rely on two of Storybook's features to handle this: [decorators](../writing-stories/decorators.md) and [globals](../essentials/toolbars-and-globals.md#globals). To handle the CSS logic, we must include some helper functions to inject and remove the stylesheets from the DOM. Start by creating the helper file with the following content:
-The new version is made smarter by [`useParameter`](./addons-api.md#useparameter), which is a [React hook](https://reactjs.org/docs/hooks-intro.html) that updates the parameter value and re-renders the panel every time the story changes.
+Next, create the file with the styles we want to inject with the following content:
+
+
-The [addon API](./addons-api.md) provides hooks like this, so all of that communication can happen behind the scenes. That means you can focus on your addon's functionality.
+
-### Using the addon with a story
+
-When Storybook was initialized, it provided a small set of example stories. Change your `Button.stories.js` to the following:
+Since the addon can be active in both the story and documentation modes, the DOM node for Storybook's preview `iframe` is different in these two modes. In fact, Storybook renders multiple story previews on one page when in documentation mode. Therefore, we'll need to choose the correct selector for the DOM node where the styles will be injected and ensure the CSS is scoped to that particular selector. That mechanism is provided as an example within the `src/withGlobals.ts` file, which we'll use to connect the styling and helper functions to the addon logic. Update the file to the following:
-After applying the changes to the story, the Storybook UI will show the following:
+## Packaging and publishing
-
+Storybook addons, similar to most packages in the JavaScript ecosystem, are distributed as NPM packages. However, they have specific criteria that need to be met to be published to NPM and crawled by the integration catalog:
+
+1. Have a `dist` folder with the transpiled code.
+2. A `package.json` file declaring:
+ - Peer dependencies
+ - Module-related information
+ - Integration catalog metadata
+
+### Module Metadata
+
+The first category of metadata is related to the addon itself. This includes the entry for the module and which files to include when the addon is published. And all the peer-dependencies of the addon (e.g., `react`,`react-dom`, and Storybook's related APIs).
+
+```json
+{
+ "exports": {
+ ".": {
+ "require": "./dist/index.js",
+ "import": "./dist/index.mjs",
+ "types": "./dist/index.d.ts"
+ },
+ "./manager": {
+ "require": "./dist/manager.js",
+ "import": "./dist/manager.mjs",
+ "types": "./dist/manager.d.ts"
+ },
+ "./preview": {
+ "require": "./dist/preview.js",
+ "import": "./dist/preview.mjs",
+ "types": "./dist/preview.d.ts"
+ },
+ "./package.json": "./package.json"
+ },
+ "main": "dist/index.js",
+ "module": "dist/index.mjs",
+ "types": "dist/index.d.ts",
+ "files": ["dist/**/*", "README.md", "*.js", "*.d.ts"],
+ "peerDependencies": {
+ "@storybook/blocks": "^7.0.0",
+ "@storybook/components": "^7.0.0",
+ "@storybook/core-events": "^7.0.0",
+ "@storybook/manager-api": "^7.0.0",
+ "@storybook/preview-api": "^7.0.0",
+ "@storybook/theming": "^7.0.0",
+ "@storybook/types": "^7.0.0",
+ "react": "^16.8.0 || ^17.0.0 || ^18.0.0",
+ "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0"
+ }
+}
+```
+
+#### Why peer-dependencies?
+
+A standard practice in the JavaScript ecosystem ensuring compatibility between modules or packages that are meant to work together, often in a plugin or extension scenario. Peer-dependencies are dependencies that are not bundled with the addon but are expected to be installed by the consumer of the addon. When a module relies on a specific version of another module, it might assume certain features, APIs, or behavior provided by that dependency. By specifying a peer dependency, the module can indicate its compatibility requirements and avoid potential conflicts or unexpected behavior due to incompatible versions.
+
+### Integration Catalog Metadata
+
+The second metadata category is related to the [integration catalog](https://storybook.js.org/integrations). Most of this information is already pre-configured by the Addon Kit. However, items like the display name, icon, and frameworks must be configured via the `storybook` property to be displayed in the catalog.
+
+```json
+{
+ "name": "my-storybook-addon",
+ "version": "1.0.0",
+ "description": "My first storybook addon",
+ "author": "Your Name",
+ "storybook": {
+ "displayName": "My Storybook Addon",
+ "unsupportedFrameworks": ["react-native"],
+ "icon": "https://yoursite.com/link-to-your-icon.png"
+ },
+ "keywords": ["storybook-addons", "appearance", "style", "css", "layout", "debug"]
+}
+```
+
+
-### Root level preset.js
+ℹ️ The `storybook` configuration element includes additional properties that help customize the addon's searchability and indexing. For more information, see the [Integration catalog documentation](./integration-catalog.md).
-Before publishing the addon, we'll need to make one last change. In the root directory of the addon, create a new file called `preset.js` and add the following:
+
+
+One essential item to note is the `keywords` property as it maps to the catalog's tag system. Adding the `storybook-addons` ensures that the addon is discoverable in the catalog when searching for addons. The remaining keywords help with the searchability and categorization of the addon.
+
+### Publishing to NPM
+
+Once you're ready to publish your addon to NPM, the Addon Kit comes pre-configured with the [Auto](https://github.com/intuit/auto) package for release management. It generates a changelog and uploads the package to NPM and GitHub automatically. Therefore, you need to configure access to both.
+
+1. Authenticate using [npm adduser](https://docs.npmjs.com/cli/v9/commands/npm-adduser)
+2. Generate a [access token](https://docs.npmjs.com/creating-and-viewing-access-tokens#creating-access-tokens) with both `read` and `publish` permissions.
+3. Create a [personal access token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) with `repo` and `workflow` scoped permissions.
+4. Create a `.env` file in the root of your project and add the following:
+
+```plaintext
+GH_TOKEN=value_you_just_got_from_github
+NPM_TOKEN=value_you_just_got_from_npm
+```
+
+Next, run the following command to create labels on GitHub. You'll use these labels to categorize changes to the package.
+
+```shell
+npx auto create-labels
+```
+
+Finally, run the following command to create a release for your addon. This will build and package the addon code, bump the version, push the release into GitHub and npm, and generate a changelog.
-This auto-registers the addon without any additional configuration from the user. Storybook looks for either a `preset.js` or a `manager.js` file located at the root level.
-
-### Packaging and publishing
-
-Now that you've seen how to create a bare-bones addon let's see how to share it with the community. Before we begin, make sure your addon meets the following requirements:
-
-- `package.json` file with metadata about the addon
-- Peer dependencies of `react` and `@storybook/addons`
-- `preset.js` file at the root level written as an ES5 module
-- `src` directory containing the ES6 addon code
-- `dist` directory containing transpiled ES5 code on publish
-- [GitHub](https://github.com/) account to host your code
-- [NPM](https://www.npmjs.com/) account to publish the addon
-
-Reference the [storybook-addon-outline](https://www.npmjs.com/package/storybook-addon-outline) to see a project that meets these requirements.
-
-Learn how to [add to the addon catalog](../addons/integration-catalog.md#addons).
+### CI automation
-### More guides and tutorials
+By default, the Addon Kit comes pre-configured with a GitHub Actions workflow, enabling you to automate the release management process. This ensures that the package is always up to date with the latest changes and that the changelog is updated accordingly. However, you'll need additional configuration to use your NPM and GitHub tokens to publish the package successfully. In your repository, click the **Settings** tab, then the **Secrets and variables** dropdown, followed by the **Actions** item. You should see the following screen:
-In the previous example, we introduced the structure of an addon but barely scratched the surface of what addons can do.
+
-To dive deeper, we recommend Storybook's [creating an addon](https://storybook.js.org/tutorials/create-an-addon/) tutorial. It’s an excellent walkthrough covering the same ground as the above introduction but goes further and leads you through the entire process of creating a realistic addon.
+Then, click the **New repository secret**, name it `NPM_TOKEN`, and paste the token you generated earlier. Whenever you merge a pull request to the default branch, the workflow will run and publish a new release, automatically incrementing the version number and updating the changelog.
-### Addon kit
+## Learn more about the Storybook addon ecosystem
-To help you jumpstart the addon development, the Storybook maintainers created an [`addon-kit`](https://github.com/storybookjs/addon-kit), use it to bootstrap your next addon.
+- [Types of addons](./addon-types.md) for other types of addons
+- Writing addons for the basics of addon development
+- [Presets](./writing-presets.md) for preset development
+- [Integration catalog](./integration-catalog.md) for requirements and available recipes
+- [API reference](./addons-api.md) to learn about the available APIs
diff --git a/docs/addons/writing-presets.md b/docs/addons/writing-presets.md
index 4a8eca84a871..57d243ac74b3 100644
--- a/docs/addons/writing-presets.md
+++ b/docs/addons/writing-presets.md
@@ -2,237 +2,201 @@
title: 'Write a preset addon'
---
-[Storybook preset addons](./addon-types.md#preset-addons) are grouped collections of `babel`, `webpack`, and `addons` configurations that support specific use cases in Storybook, such as TypeScript or MDX support.
+Storybook presets are pre-configured settings or configurations that enable developers quickly set up and customize their environment with a specific set of features, functionalities, or integrations.
-This doc covers the [presets API](#presets-api) and how to use the presets mechanism for [advanced configuration](#advanced-configuration).
+## How presets work
-## Presets API
+Preset addons allow developers to compose various configuration options and plugins via APIs to integrate with Storybook and customize its behavior and functionality. Typically, presets are separated into two files, each with its specific role.
-A preset is a set of hooks that are called by Storybook on initialization and can override configurations for `babel`, `webpack`, `addons`, and `entries`.
+### Local presets
-Each configuration has a similar signature, accepting a base configuration object and options, as in this Webpack example:
+This type of preset allows you to encapsulate and organize configurations specific to the addon, including [builder](../builders/overview.md) support, [Babel](https://babeljs.io/), or third-party integrations. For example:
-### Babel
-
-The babel functions `babel` and `babelDefault` all configure babel in different ways.
-
-All functions take a [Babel configuration object](https://babeljs.io/docs/en/configuration) as their argument and can modify it or return a new object.
+### Root-level presets
-For example, Storybook's Mihtril support uses plugins internally and here's how it configures babel:
+This type of preset is user-facing and responsible for registering the addon without any additional configuration from the user by bundling Storybook-related features (e.g., [parameters](../writing-stories/parameters.md)) via the [`previewAnnotations`](../api/main-config-preview-annotations.md) and UI related features (e.g., addons) via the `managerEntries` API. For example:
-- `babel` is applied to the preview config, after it has been initialized by storybook
-- `babelDefault` is applied to the preview config before any user presets have been applied
-
-### Webpack
+## Presets API
-The Webpack functions `webpack`, `webpackFinal`, and `managerWebpack` configure Webpack.
+When writing a preset, you can access a select set of APIs to interact with the Storybook environment, including the supported builders (e.g., Webpack, Vite), the Storybook configuration, and UI. Below are the available APIs you can use when writing a preset addon.
-All functions take a [webpack4 configuration object](https://webpack.js.org/configuration/).
+### Babel
-For example, here is how Storybook automatically adopts `create-react-app`'s configuration if it's installed, where `applyCRAWebpackConfig` is a set of smart heuristics for modifying the input config.
+To customize Storybook's Babel configuration and add support for additional features, you can use the [`babelDefault`](../api/main-config-babel-default.md) API. It will apply the provided configuration ahead of any other user presets, which can be further customized by the end user via the [`babel`](../api/main-config-babel.md) configuration option. For example:
-- `webpack` is applied to the preview config after it has been initialized by Storybook
-- `webpackFinal` is applied to the preview config after all user presets have been applied
-- `managerWebpack` is applied to the manager config
-
-As of Storybook 6.3, Storybook can run with either `webpack4` or `webpack5` builder. If your addon needs to know which version of Webpack it's running inside, the version and the actual Webpack instance itself are both available inside your preset:
-
-
-
-
-
-
+### Builders
-### Manager entries
+By default, Storybook provides support for the leading industry builders, including [Webpack](../builders/webpack.md) and [Vite](../builders/vite.md). If you need additional features for any of these builders, you can use APIs to extend the builder configuration based on your specific needs.
-The addon config `managerEntries` allows you to add addons to Storybook from within a preset. For addons that require custom Webpack/Babel configuration, it is easier to install the preset, and it will take care of everything.
+#### Vite
-For example, the Storysource preset contains the following code:
+If you are creating a preset and want to include Vite support, the `viteFinal` API can be used to modify the default configuration and enable additional features. For example:
-This is equivalent to [registering the addon manually](../get-started/browse-stories.md#addons) in [`main.js`](../configure/overview.md#configure-story-rendering):
+#### Webpack
+
+To customize the Webpack configuration in Storybook to add support for additional file types, apply specific loaders, configure plugins, or make any other necessary modifications, you can use the `webpackFinal` API. Once invoked, it will extend the default Webpack configuration with the provided configuration. An example of this would be:
-### Preview entries
-
-The addon `config` function allows you to add extra preview configuration from within a preset, for example to add parameters or decorators from an addon.
+### ManagerEntries
-For example, the Backgrounds preset contains the following code:
+If you're writing a preset that loads third-party addons, which you may not have control over, but require access to specific features or additional configuration, you can use the `managerEntries` API. For example:
-Which in turn invokes:
+### PreviewAnnotations
+
+If you need additional settings to render stories for a preset, like [decorators](../writing-stories/decorators.md) or [parameters](../writing-stories/parameters.md), you can use the `previewAnnotations` API. For example, to apply a decorator to all stories, create a preview file that includes the decorator and make it available to the preset as follows:
-This is equivalent to exporting the `backgrounds` parameter manually in `main.js`.
+## Advanced configuration
-### Addons
-
-For users, the name `managerEntries` might be a bit too technical, so instead both users and preset-authors can simply use the `addons` property:
+The presets API is designed to be flexible and allow you to customize Storybook to your specific needs, including using presets for more advanced use cases without publishing them. In such cases, you can rely on a private preset. These private presets contain configuration options meant for development purposes and not for end-users. The `.storybook/main.js|ts` file is an example of such a private preset that empowers you to modify the behavior and functionality of Storybook.
-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 a manager entry using the `managerEntries` key.
+### Addons
-Here's what it looks when combining presets and manager entries in the `addons` property:
+For addon consumers, the [`managerEntries`](#managerentries) API can be too technical, making it difficult to use. To make it easier to add addons to Storybook, the preset API provides the [`addons`](../api/main-config-addons.md) API, which accepts an array of addon names and will automatically load them for you. For example:
-### 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.
-
-## Advanced Configuration
-
-The presets API is also more powerful than the [standard configuration options](../builders/webpack.md#override-the-default-configuration) available in Storybook, so it's also possible to use presets for more advanced configuration without actually publishing a preset yourself.
+The array of values supports references to additional presets and addons that should be included in the manager. Storybook will automatically detect whether the provided value is a preset or an addon and load it accordingly.
-For example, some users want to configure the Webpack for Storybook's UI and addons ([issue](https://github.com/storybookjs/storybook/issues/4995)), but this is not possible using [standard Webpack configuration](../builders/webpack.md#configure) (it used to be possible before SB4.1). However, you can achieve this with a private preset.
-
-If it doesn't exist yet, create a file `.storybook/main.js`:
-
-
-
-
-
-
+### Entries
-### Preview/Manager templates
+Entries are the place to register entry points for the preview. This feature can be utilized to create a configure-storybook preset that automatically loads all `*.stories.js` files into Storybook, eliminating the need for users to copy-paste the same configuration repeatedly.
-It's also possible to programmatically modify the preview head/body HTML using a preset, similar to the way `preview-head.html`/`preview-body.html` can be used to [configure story rendering](../configure/story-rendering.md). The `previewHead` and `previewBody` functions accept a string, which is the existing head/body, and return a modified string.
+### UI configuration
-For example, the following snippet adds a style tag to the preview head programmatically:
+The Storybook preset API also provides access to the UI configuration, including the `head` and `body` HTML elements of the preview, configured by the [`previewHead`](../api/main-config-preview-head.md) and [`previewBody`](../api/main-config-preview-body.md) APIs. Both allow you to set up Storybook in a way that is similar to using the [`preview-head.html`](../configure/story-rendering.md#adding-to-head) and [`preview-body.html`](../configure/story-rendering.md#adding-to-body) files. These methods accept a string and return a modified version, injecting the provided content into the HTML element.
-Similarly, the `managerHead` can be used to modify the surrounding "manager" UI, analogous to `manager-head.html`.
-
-Finally, the preview's main page _template_ can also be overridden using the `previewMainTemplate`, which should return a reference to a file containing an `.ejs` template that gets interpolated with some environment variables. For an example, see the [Storybook's default template](https://github.com/storybookjs/storybook/blob/next/code/lib/core-common/templates/preview.ejs).
-
-## Sharing advanced configuration
-
-Change your `main.js` file to:
+Additionally, if you need to customize the manager (i.e., where Storybook’s search, navigation, toolbars, and addons render), you can use the [`managerHead`](../api/main-config-manager-head.md) to modify the UI, similar to how you would do it with the `manager-head.html` file. For example:
-and extract the configuration to a new file `./storybook/my-preset.js`:
+However, if you need, you can also customize the template used by Storybook to render the UI. To do so, you can use the `previewMainTemplate` API and provide a reference for a custom template created as a `ejs` file. For an example of how to do this, see the [template](https://github.com/storybookjs/storybook/blob/next/code/builders/builder-webpack5/templates/preview.ejs) used by the Webpack 5 builder.
-
+## Troubleshooting
-
+### Storybook doesn't load files in my preset
-
+As Storybook relies on [esbuild](https://esbuild.github.io/) instead of Webpack to build the UI, presets that depend on the `managerWebpack` API to configure the manager or load additional files other than CSS or images will no longer work. We recommend removing it from your preset and adjusting your configuration to convert any additional files to JavaScript.
-Place your `my-preset.js` file wherever you want, if you want to share it far and wide you'll want to make it its own package.
+- [Types of addons](./addon-types.md) for other types of addons
+- [Writing addons](./writing-addons.md) for the basics of addon development
+- Presets for preset development
+- [Integration catalog](./integration-catalog.md) for requirements and available recipes
+- [API reference](./addons-api.md) to learn about the available APIs
diff --git a/docs/api/main-config-manager-head.md b/docs/api/main-config-manager-head.md
index 1dfdabc54ae9..d44eb52f4a83 100644
--- a/docs/api/main-config-manager-head.md
+++ b/docs/api/main-config-manager-head.md
@@ -6,7 +6,7 @@ Parent: [main.js|ts configuration](./main-config.md)
Type: `(head: string) => string`
-Programmatically adjust the manager's `` of your Storybook. For example, load a custom font or add a script. Most often used by [addon authors](../addons/writing-presets.md#babel).
+Programmatically adjust the manager's `` of your Storybook. For example, load a custom font or add a script. Most often used by [addon authors](../addons/writing-presets.md#ui-configuration).
diff --git a/docs/api/main-config-preview-body.md b/docs/api/main-config-preview-body.md
index ed9df6ee072e..f35a05a0c4e0 100644
--- a/docs/api/main-config-preview-body.md
+++ b/docs/api/main-config-preview-body.md
@@ -6,7 +6,7 @@ Parent: [main.js|ts configuration](./main-config.md)
Type: `(body: string) => string`
-Programmatically adjust the [preview ``](../configure/story-rendering.md#adding-to-body) of your Storybook. Most often used by [addon authors](../addons/writing-presets.md#babel).
+Programmatically adjust the [preview ``](../configure/story-rendering.md#adding-to-body) of your Storybook. Most often used by [addon authors](../addons/writing-presets.md#ui-configuration).
diff --git a/docs/api/main-config-preview-head.md b/docs/api/main-config-preview-head.md
index df4382095c53..af29ce4442f0 100644
--- a/docs/api/main-config-preview-head.md
+++ b/docs/api/main-config-preview-head.md
@@ -6,7 +6,7 @@ Parent: [main.js|ts configuration](./main-config.md)
Type: `(head: string) => string`
-Programmatically adjust the [preview ``](../configure/story-rendering.md#adding-to-head) of your Storybook. Most often used by [addon authors](../addons/writing-presets.md#babel).
+Programmatically adjust the [preview ``](../configure/story-rendering.md#adding-to-head) of your Storybook. Most often used by [addon authors](../addons/writing-presets.md#ui-configuration).
diff --git a/docs/configure/story-rendering.md b/docs/configure/story-rendering.md
index f930fe1e3765..b4b157569eab 100644
--- a/docs/configure/story-rendering.md
+++ b/docs/configure/story-rendering.md
@@ -24,7 +24,7 @@ Storybook will inject these tags into the _preview iframe_ where your components
-It's also possible to modify the preview head HTML programmatically using a preset defined in the `main.js` file. For more information see [Preview/Manager templates](../addons/writing-presets.md#previewmanager-templates).
+However, it's also possible to modify the preview head HTML programmatically using a preset defined in the `main.js` file. Read the [presets documentation](../addons/writing-presets.md#ui-configuration) for more information.
## Adding to <body>
@@ -60,4 +60,4 @@ Storybook will inject these tags into the _preview iframe_ where your components
-Similarly to the preview head HTML, preview body HTML can also be updated programmatically using a preset. See [Preview/Manager templates](../addons/writing-presets.md#previewmanager-templates) for more information.
+Just like how you have the ability to customize the preview `head` HTML tag, you can also follow the same steps to customize the preview `body` with a preset. To obtain more information on how to do this, refer to the [presets documentation](../addons/writing-presets.md#ui-configuration).
diff --git a/docs/contribute/framework.md b/docs/contribute/framework.md
index a84cc735f728..d3912bfd80ad 100644
--- a/docs/contribute/framework.md
+++ b/docs/contribute/framework.md
@@ -130,7 +130,7 @@ The [preset API](../addons/writing-presets) is where you will configure the Stor
#### `preview.js` ([example](https://github.com/storybookjs/storybook/blob/next/code/frameworks/nextjs/src/preview.tsx))
-The (optional) [preview API](../configure/overview#configure-story-rendering) is where you configure the rendering of stories, such as global decorators or initializing some runtime config needed for your framework to behave as expected. If your framework requires this file, note that you also need to [configure the `previewAnnotations` in `preset.js`](https://github.com/storybookjs/storybook/blob/next/code/frameworks/nextjs/src/preset.ts#L66-L69).
+The (optional) [preview API](../configure/overview#configure-story-rendering) is where you configure the rendering of stories, such as global decorators or initializing some runtime config needed for your framework to behave as expected. If your framework requires this file, note that you also need to [configure the `previewAnnotations` in `preset.js`](https://github.com/storybookjs/storybook/blob/next/code/frameworks/nextjs/src/preset.ts#L71-L74).
#### `types.ts` ([example](https://github.com/storybookjs/storybook/blob/next/code/frameworks/nextjs/src/types.ts))
diff --git a/docs/snippets/common/main-config-preview.body.js.mdx b/docs/snippets/common/main-config-preview.body.js.mdx
new file mode 100644
index 000000000000..a1c4e6b2f441
--- /dev/null
+++ b/docs/snippets/common/main-config-preview.body.js.mdx
@@ -0,0 +1,12 @@
+```js
+// .storybook/main.js
+
+export default {
+ previewBody: (body) => `
+ ${body}
+ ${
+ process.env.ANALYTICS_ID ? '' : ''
+ }
+ `,
+};
+```
diff --git a/docs/snippets/common/main-config-preview.body.ts.mdx b/docs/snippets/common/main-config-preview.body.ts.mdx
new file mode 100644
index 000000000000..d721710529ed
--- /dev/null
+++ b/docs/snippets/common/main-config-preview.body.ts.mdx
@@ -0,0 +1,17 @@
+```ts
+// .storybook/main.ts
+
+// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
+import type { StorybookConfig } from '@storybook/your-framework';
+
+const config: StorybookConfig = {
+ previewBody: (body) => `
+ ${body}
+ ${
+ process.env.ANALYTICS_ID ? '' : ''
+ }
+ `,
+};
+
+export default config;
+```
diff --git a/docs/snippets/common/main-config-preview.head.js.mdx b/docs/snippets/common/main-config-preview.head.js.mdx
new file mode 100644
index 000000000000..059f91223503
--- /dev/null
+++ b/docs/snippets/common/main-config-preview.head.js.mdx
@@ -0,0 +1,14 @@
+```js
+// .storybook/main.js
+
+export default {
+ previewHead: (head) => `
+ ${head}
+
+ `,
+};
+```
diff --git a/docs/snippets/common/main-config-preview.head.ts.mdx b/docs/snippets/common/main-config-preview.head.ts.mdx
new file mode 100644
index 000000000000..2623d0c3c7e4
--- /dev/null
+++ b/docs/snippets/common/main-config-preview.head.ts.mdx
@@ -0,0 +1,19 @@
+```ts
+// .storybook/main.ts
+
+// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
+import type { StorybookConfig } from '@storybook/your-framework';
+
+const config: StorybookConfig = {
+ previewHead: (head) => `
+ ${head}
+
+ `,
+};
+
+export default config;
+```
diff --git a/docs/snippets/common/my-addon-babel-configuration.js.mdx b/docs/snippets/common/my-addon-babel-configuration.js.mdx
deleted file mode 100644
index 7fdc781547ae..000000000000
--- a/docs/snippets/common/my-addon-babel-configuration.js.mdx
+++ /dev/null
@@ -1,7 +0,0 @@
-```js
-// /my-addon/.babelrc.js
-
-export default {
- presets: ['@babel/preset-env', '@babel/preset-react'],
-};
-```
diff --git a/docs/snippets/common/my-addon-initial-panel-state.js.mdx b/docs/snippets/common/my-addon-initial-panel-state.js.mdx
deleted file mode 100644
index a6b69c859a21..000000000000
--- a/docs/snippets/common/my-addon-initial-panel-state.js.mdx
+++ /dev/null
@@ -1,27 +0,0 @@
-```js
-// /my-addon/src/manager.js
-
-import React from 'react';
-
-import { addons, types } from '@storybook/manager-api';
-
-import { AddonPanel } from '@storybook/components';
-
-const ADDON_ID = 'myaddon';
-const PANEL_ID = `${ADDON_ID}/panel`;
-
-// give a unique name for the panel
-const MyPanel = () =>