⚡ Storybook Addon Live Examples ⚡

Code playground with live editing inside your storybook

• 🧑‍💻 Play with code without 3rd-party service services like codepen
• 👥 Share examples with others
• 🐛 Share links to bug reproductions with others
• 🧱 Check how the components work together
• Typescript supported

Getting started

1. Install addon

1TODO

2. Register addon in main.js

1module.exports = {
2    addons: ['storybook-addon-live-examples'],
3};

3. Setup addon in preview.js (optional step)

1import { addons } from '@storybook/addons';
2import { LIVE_EXAMPLES_ADDON_ID } from 'storybook-addon-live-examples';
3import theme from 'prism-react-renderer/themes/github';
4
5import AllComponents from '../packages';
6
7addons.setConfig({
8    [LIVE_EXAMPLES_ADDON_ID]: {
9        // custom theme from prism-react-renderer (optional)
10        editorTheme: theme,
11        // internationalization (optional)
12        copyText: ['Copy', 'Copied'],
13        expandText: ['Show code', 'Hide code'],
14        shareText: ['Share', 'Shared'],
15        // scope (globally accessible components & functions) (optional)
16        scope: {
17            ...AllComponents,
18            someFunction: () => 42
19        },
20    },
21});

4. Configure webpack (for storybook 7 only)

1const { patchWebpackConfig } = require('storybook-addon-live-examples/dist/cjs/utils');
2
3module.exports = {
4    webpackFinal: (config) => {
5        patchWebpackConfig(config);
6        
7        return config;
8    }
9};

Usage

CSF

Live examples will be rendered instead of the default addon-docs canvas.

Your can customize examples by parameters:

1export default {
2    title: 'Components/Button',
3    parameters: {
4        scope: {
5            scopeValue,
6        },
7    }
8};
9
10const scopeValue = 42;
11
12export const Primary = () => <button>{scopeValue}</button>;
13
14Primary.parameters = {
15    expanded: true
16};
17
18export const Secondary = () => <button>{scopeValue}</button>;

NOTE: Most likely you will get errors after addon installing. Don't panic, just pass all variables that are used in your story to scope

MDX

Inside MDX-based stories you can write your code examples with plain markdown.

Just put your code inside triple quotes

1|```tsx live
2|<h4>Wow, so simple</h4>
3|```

Or render custom Canvas

1// Import custom Canvas from addon
2import { Canvas } from 'storybook-addon-live-examples';
3
4<Canvas live={true} scope={{ value: 42 }}>
5    <h4>Wow, so simple, {value}</h4>
6</Canvas>

Or use Example directly

1import { Example } from 'storybook-addon-live-examples';
2
3<Example live={true} code={`<h4>Wow, so simple</h4>`} />

CSF With MDX

1// Button.stories.js
2
3import mdx from './Button.mdx';
4
5export default {
6    title: 'Components/Button',
7    parameters: {
8        docs: {
9            page: mdx,
10        },
11    },
12};
13
14const scopeValue = 42;
15
16export const Primary = () => <button>{scopeValue}</button>;
17
18Primary.parameters = {
19    scope: {
20        scopeValue,
21    },
22};

1// Button.mdx
2
3import { ArgsTable, Story } from '@storybook/addon-docs';
4
5import { Button } from './Button';
6
7# Button
8
9<ArgsTable of={Button} />
10
11<Story id='components-button--primary' />

Example props

You can customize the display of examples with props or metastring

live

1|```tsx live
2|<span>This example can be edited</span>
3|```

1<span>This example can be edited</span>

expanded

1|```tsx live expanded
2|<span>This example will be rendered with expanded code sources</span>
3|```

1<span>This example will be rendered with expanded code sources</span>

Complex examples

1render(() => {
2    const [counter, setCounter] = React.useState(0);
3    return (
4        <>
5            <h2>Super live counter: {counter}</h2>
6            <button type='button' onClick={() => setCounter((c) => c + 1)}>
7                Increment
8            </button>
9        </>
10    );
11});

Scope

Storybook-addon-live-examples uses react-live under the hood.

Scope allows you to pass some globals to your code examples. By default it injects React only, which means that you can use it in code like this:

1render(() => {
2//                                ↓↓↓↓↓
3    const [counter, setCounter] = React.useState(0);
4    return counter;
5}

- Pass your own components to scope by props

1import { Canvas } from 'storybook-addon-live-examples';
2import MyComponent from '../packages/my-component';
3
4<Canvas live={true} scope={{ MyComponent }}>
5    <MyComponent>Amazing</MyComponent>
6</Canvas>

- Setup scope globally

This is the easiest way to setup scope once for an entire project

1//.storybook/manager.js
2
3import { addons } from '@storybook/addons';
4import { LIVE_EXAMPLES_ADDON_ID } from 'storybook-addon-live-examples';
5
6addons.setConfig({
7    [LIVE_EXAMPLES_ADDON_ID]: {
8        scope: {
9            MyComponent,
10        },
11    },
12});

1<MyComponent>Now, you can use MyComponent in all examples</MyComponent>

- Setup scope inside monorepo

This is an example of how you can add all used components and helpers to the scope.

1// .storybook/scope.ts
2
3import { ComponentType } from 'react';
4
5import * as icons from 'some-icons-pack';
6import * as knobs from '@storybook/addon-knobs';
7
8// packages/{componentName}/index.ts
9const req = require.context('../packages', true, /^\.\/(.*)\/index.ts$/);
10
11const components = req.keys().reduce((acc: Record<string, ComponentType>, key) => {
12    Object.entries(req(key)).forEach(([componentName, component]: [string, any]) => {
13        acc[componentName] = component;
14    });
15
16    return acc;
17}, {});
18
19export default {
20    ...components,
21    ...icons,
22    ...knobs,
23};
24
25// .storybook/manager.js
26
27import scope from './scope';
28
29addons.setConfig({
30    [LIVE_EXAMPLES_ADDON_ID]: {
31        scope,
32    },
33});