Skip to content

Commit

Permalink
Merge pull request #17221 from storybookjs/chore_docs_fix_addon_knowl…
Browse files Browse the repository at this point in the history 
…edge_base

Chore: (Docs) Minor tweaks to the addon knowledge base
  • Loading branch information
@jonniebigodes
jonniebigodes authored Jan 12, 2022
2 parents 805db97 + 72bcc2c commit ad0dc42
Show file tree
Hide file tree
Showing 2 changed files with 50 additions and 22 deletions.
56 changes: 34 additions & 22 deletions docs/addons/addon-knowledge-base.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Addon knowledge base
---

Once you understand the basics of writing addons, there are a variety of common enhancements to make your addon better. This page details additional information about addon creation. Use it as a quick reference guide when creating your own addons.
Once you understand the basics of writing addons, there are a variety of common enhancements to make your addon better. This page details additional information about addon creation. Use it as a quick reference guide when creating your own addons.

### Disable the addon panel

Expand Down Expand Up @@ -34,25 +34,23 @@ Then when adding a story, you can pass a disabled parameter.

### Style your addon

Storybook uses [Emotion](https://emotion.sh/docs/introduction) for styling. Alongside with a theme which you can customize!
Storybook uses [Emotion](https://emotion.sh/docs/introduction) for styling. Alongside with a theme that you can customize!

We recommend you also to use Emotion to style your addon’s UI components. That allows you to use the active Storybook theme to deliver a seamless developer experience.
If you don’t want to use Emotion, you can use inline styles or another css-in-js lib. You can receive the theme as a prop by using the `withTheme` hoc from Emotion. [Read more about theming](../configure/theming.md).
We recommend using Emotion to style your addon’s UI components. That allows you to use the active Storybook theme to deliver a seamless developer experience.
If you don’t want to use Emotion, you can use inline styles or another css-in-js lib. You can receive the theme as a prop by using Emotion's `withTheme` HOC. [Read more about theming](../configure/theming.md).

### Storybook components

Addon authors can develop their UIs using any React library. But we recommend using Storybook’s own UI components in `@storybook/components` to build addons faster. When you use Storybook components you get:
Addon authors can develop their UIs using any React library. But we recommend using Storybook’s UI components in `@storybook/components` to build addons faster. When you use Storybook components, you get:

- Battle-tested off-the-shelf components
- Storybook native look and feel
- Built-in support for Storybook theming


Use the components listed below with your next addon.

Use the components listed below with your next addon.

| Component | Source | Story |
|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Action Bar | [See component implementation](https://github.com/storybookjs/storybook/blob/master/lib/components/src/ActionBar/ActionBar.tsx) | [See component story](https://5a375b97f4b14f0020b0cda3-wbeulgbetj.chromatic.com/?path=/story/basics-actionbar--single-item) |
| Addon Panel | [See component implementation](https://github.com/storybookjs/storybook/blob/master/lib/components/src/addon-panel/addon-panel.tsx) | N/A |
| Badge | [See component implementation](https://github.com/storybookjs/storybook/blob/master/lib/components/src/Badge/Badge.tsx) | [See component story](https://5a375b97f4b14f0020b0cda3-wbeulgbetj.chromatic.com/?path=/story/basics-badge--all-badges) |
Expand All @@ -68,23 +66,21 @@ Use the components listed below with your next addon.
| ToolTip | [See component implementation](https://github.com/storybookjs/storybook/blob/master/lib/components/src/tooltip/Tooltip.tsx) | [See component story](https://5a375b97f4b14f0020b0cda3-wbeulgbetj.chromatic.com/?path=/story/basics-tooltip-tooltip--basic-default) |
| Zoom | [See component implementation](https://github.com/storybookjs/storybook/blob/master/lib/components/src/Zoom/Zoom.tsx) | [See component story](https://5a375b97f4b14f0020b0cda3-wbeulgbetj.chromatic.com/?path=/story/basics-zoom--element-actual-size) |


Complementing the components, also included is a set of UI primitives. Use the content listed below as reference for styling your addon.
Complementing the components, also included is a set of UI primitives. Use the content listed below as a reference for styling your addon.

| Component | Source | Story |
|---------------------------------|--------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
| ------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| Color Pallette (see note below) | [See implementation](https://github.com/storybookjs/storybook/tree/master/lib/components/src/Colors) | [See story](https://5a375b97f4b14f0020b0cda3-wbeulgbetj.chromatic.com/?path=/story/basics-colorpalette--page) |
| Icon | [See implementation](https://github.com/storybookjs/storybook/blob/master/lib/components/src/icon/icons.tsx) | [See story](https://5a375b97f4b14f0020b0cda3-wbeulgbetj.chromatic.com/?path=/story/basics-icon--labels) |
| Typography | [See implementation](https://github.com/storybookjs/storybook/tree/master/lib/components/src/typography) | [See story](https://5a375b97f4b14f0020b0cda3-wbeulgbetj.chromatic.com/?path=/story/basics-typography--all) |

| Typography | [See implementation](https://github.com/storybookjs/storybook/tree/master/lib/components/src/typography) | [See story](https://5a375b97f4b14f0020b0cda3-wbeulgbetj.chromatic.com/?path=/story/basics-typography--all) |

<div class="aside">
The color palette implemented by <code>@storybook/components</code> is a high-level abstraction of the <a href="https://github.com/storybookjs/storybook/tree/next/lib/theming/src"><code>@storybook/theming</code></a> package.
</div>

### Build system

When you're developing your addon as a package, you can’t use `npm link` to add it to your project. List your addon as a local dependency into your package.json:
When you're developing your addon as a package, you can’t use `npm link` to add it to your project. List your addon as a local dependency into your package.json:

```json
{
Expand All @@ -100,22 +96,38 @@ Run either <code>yarn</code> or <code>npm install</code> to install the addon.

### Hot module replacement

While developing your addon you can configure HMR (hot module replacement) to reflect the changes made.
While developing your addon, you can configure HMR (hot module replacement) to reflect the changes made.

#### Standalone Storybook addons
### Standalone Storybook addons

If you're developing a standalone addon, add a new script to `package.json` with the following:
If you're developing a standalone addon, add a new script to `package.json` with the following:

```json
{
"scripts":{
"start": "npm run build -- --watch",
"scripts": {
"start": "npm run build -- --watch"
}
}
```

#### Local Storybook addons

If you're developing a local Storybook addon that is built on top of an existing Storybook installation HMR (hot module replacement) is available out of the box.
If you're developing a local Storybook addon built on top of an existing Storybook installation, HMR (hot module replacement) is available out of the box.

If you don't see the changes being reflected, add the flag `--no-manager-cache` to the `storybook` script and restart Storybook.

### Composing addons in presets

If you're working on a preset that loads third-party addons, which you don't have control over, and you need access to certain features (e.g., decorators) or provide additional configurations. In that case, you'll need to update your preset to the following to allow you to load and configure the other addons:

<!-- prettier-ignore-start -->

<CodeSnippets
paths={[
'common/storybook-addon-load-external-addons-preset.js.mdx',
]}
/>

<!-- prettier-ignore-end -->

If you don't see the changes being reflected, add the flag `--no-manager-cache` to the `storybook` script and restart Storybook.
If you have control over the addons you want to customize. In that case, you can update your preset and implement a custom function to load any additional presets and provide the necessary configuration, similar to how it's implemented in the [Essentials](../../addons/essentials/src/index.ts) addon.
16 changes: 16 additions & 0 deletions docs/snippets/common/storybook-addon-load-external-addons-preset.js.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
```js
// my-preset/index.js

function managerEntries(entry = []) {
return [...entry, require.resolve('my-other-addon/register')];
}

const config = (entry = [], options) => {
return [...entry, require.resolve('my-other-addon/addDecorator')];
};

module.exports = {
managerEntries,
config,
};
```

0 comments on commit ad0dc42

Please sign in to comment.