Skip to content

Commit

Permalink
improve bundling wording
Browse files Browse the repository at this point in the history
  • Loading branch information
JReinhold committed Nov 8, 2023
1 parent c5b420a commit 72acb34
Showing 1 changed file with 12 additions and 12 deletions.
24 changes: 12 additions & 12 deletions README.md
Expand Up @@ -72,27 +72,27 @@ Lastly, configure you addon name in `src/constants.ts`.

### Bundling

Addons have multiple ways of interacting with a Storybook project. It's recommended to understand [the basics](https://storybook.js.org/docs/react/addons/introduction) before diving in.
Addons can interact with a Storybook project in multiple ways. It is recommended to familiarize yourself with [the basics](https://storybook.js.org/docs/react/addons/introduction) before getting started.

- Manager entries are used to inject UI or behavior to the Storybook manager UI
- Preview entries are used to inject UI or behavior into the preview iframe where stories are rendered
- Presets are used to alter the configuration of a Storybook similar to how [users can configure their `main.ts` configurations](https://storybook.js.org/docs/react/api/main-config).
- Manager entries are used to add UI or behavior to the Storybook manager UI.
- Preview entries are used to add UI or behavior to the preview iframe where stories are rendered.
- Presets are used to modify the Storybook configuration, similar to how [users can configure their `main.ts` configurations](https://storybook.js.org/docs/react/api/main-config).

Each of these places are different environments where different features and modules are available, therefore it's also recommended to separate and build your modules into the same categories. Addon-kit comes preconfigured with [a bundling configuration](./tsup.config.ts) that supports this separation and you're free to modify and extend it to suit your needs.
Since each of these places represents a different environment with different features and modules, it is also recommended to split and build your modules accordingly. This addon-kit comes with a preconfigured [bundling configuration](./tsup.config.ts) that supports this split, and you are free to modify and extend it as needed.

You define which modules match which environments in the [`package.json#bundler`](./package.json) property:
You can define which modules match which environments in the [`package.json#bundler`](./package.json) property:

- `exportEntries` is a list of module entries that your users can import from manually anywhere they need to. Eg. you could have decorators that users need to import to their `preview.ts` file, or utility functions that can be used in their `main.ts` files.
- `managerEntries` is a list of module entries meant only for the manager UI. These modules will only be bundled to ESM and won't include types, since they are mostly loaded by Storybook directly anyway.
- `managerEntries` is a list of module entries meant only for the preview UI. These modules will only be bundled to ESM and won't include types, since they are mostly loaded by Storybook directly anyway.
- `exportEntries` is a list of module entries that users can manually import from anywhere they need to. For example, you could have decorators that users need to import into their `preview.ts` file or utility functions that can be used in their `main.ts` files.
- `managerEntries` is a list of module entries meant only for the manager UI. These modules will be bundled to ESM and won't include types since they are mostly loaded by Storybook directly.
- `previewEntries` is a list of module entries meant only for the preview UI. These modules will be bundled to ESM and won't include types since they are mostly loaded by Storybook directly.

#### Globalized packages

Storybook makes a pre-defined set of packages available in the manager UI and in the preview UI. In the final bundle of your addon these packages should not be included, but rather imported directly, which allows Storybook to replace those imports with the actual packages when Storybook is being built.
Storybook provides a predefined set of packages that are available in the manager UI and the preview UI. In the final bundle of your addon, these packages should not be included. Instead, the imports should stay in place, allowing Storybook to replace those imports with the actual packages during the Storybook build process.

The list of packages is different between the manager and the preview, which is why there's a slight difference between `managerEntries` and `previewEntries`. Most notably `react` and `react-dom` comes prebundled in the manager, but not in the preview. This means that your manager entries are free to use React to build UI _without_ bundling it in or having a direct reference to it, which is why it's safe to have them as a `devDependency` even though you are using it. _Having React as a peer dependency will unnecessarily require your users to install React._
The list of packages differs between the manager and the preview, which is why there is a slight difference between `managerEntries` and `previewEntries`. Most notably, `react` and `react-dom` are prebundled in the manager but not in the preview. This means that your manager entries can use React to build UI without bundling it or having a direct reference to it. Therefore, it is safe to have React as a `devDependency` even though you are using it in production. _Requiring React as a peer dependency would unnecessarily force your users to install React._

An exception to the rule above is if you're using React to inject UI into the _preview_, which doesn't come prebundled with React. In those cases you need to move `react` and `react-dom` to a peer dependency. We generally advice against this pattern since this will mean your addon can only be used in React-based Storybooks.
An exception to this rule is if you are using React to inject UI into the preview, which does not come prebundled with React. In such cases, you need to move `react` and `react-dom` to a peer dependency. However, we generally advise against this pattern since it would limit the usage of your addon to React-based Storybooks.

### Metadata

Expand Down

0 comments on commit 72acb34

Please sign in to comment.