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
```bash
TODO
```
### 2. Register addon in main.js
```js
module.exports = {
addons: ['storybook-addon-live-examples'],
};
```
### 3. Setup addon in preview.js (optional step)
```js
import { addons } from '@storybook/addons';
import { LIVE_EXAMPLES_ADDON_ID } from 'storybook-addon-live-examples';
import theme from 'prism-react-renderer/themes/github';
import AllComponents from '../packages';
addons.setConfig({
[LIVE_EXAMPLES_ADDON_ID]: {
// custom theme from prism-react-renderer (optional)
editorTheme: theme,
// internationalization (optional)
copyText: ['Copy', 'Copied'],
expandText: ['Show code', 'Hide code'],
shareText: ['Share', 'Shared'],
// scope (globally accessible components & functions) (optional)
scope: {
...AllComponents,
someFunction: () => 42
},
},
});
```
### 4. Configure webpack (for storybook 7 only)
```js
const { patchWebpackConfig } = require('storybook-addon-live-examples/dist/cjs/utils');
module.exports = {
webpackFinal: (config) => {
patchWebpackConfig(config);
return config;
}
};
```
## Usage
### CSF
Live examples will be rendered instead of the default addon-docs canvas.
Your can customize examples by parameters:
```tsx
export default {
title: 'Components/Button',
parameters: {
scope: {
scopeValue,
},
}
};
const scopeValue = 42;
export const Primary = () => ;
Primary.parameters = {
expanded: true
};
export const Secondary = () => ;
```
**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**
```markdown
|```tsx live
|
Wow, so simple
|```
```
**Or render custom Canvas**
```tsx
// Import custom Canvas from addon
import { Canvas } from 'storybook-addon-live-examples';
```
**Or use Example directly**
```tsx
import { Example } from 'storybook-addon-live-examples';
Wow, so simple`} />
```
### [CSF With MDX](https://github.com/storybookjs/storybook/blob/master/addons/docs/docs/recipes.md#csf-stories-with-arbitrary-mdx)
```tsx
// Button.stories.js
import mdx from './Button.mdx';
export default {
title: 'Components/Button',
parameters: {
docs: {
page: mdx,
},
},
};
const scopeValue = 42;
export const Primary = () => ;
Primary.parameters = {
scope: {
scopeValue,
},
};
```
```tsx
// Button.mdx
import { ArgsTable, Story } from '@storybook/addon-docs';
import { Button } from './Button';
# Button
```
## Example props
You can customize the display of examples with props or metastring
### live
```markdown
|```tsx live
|This example can be edited
|```
```
```tsx live
This example can be edited
```
### expanded
```markdown
|```tsx live expanded
|This example will be rendered with expanded code sources
|```
```
```tsx live expanded
This example will be rendered with expanded code sources
```
## Complex examples
```tsx live expanded
render(() => {
const [counter, setCounter] = React.useState(0);
return (
<>
Super live counter: {counter}
);
});
```
## Scope
Storybook-addon-live-examples uses [react-live](https://github.com/FormidableLabs/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:
```tsx
render(() => {
// ↓↓↓↓↓
const [counter, setCounter] = React.useState(0);
return counter;
}
```
#### - Pass your own components to scope by props
```tsx
import { Canvas } from 'storybook-addon-live-examples';
import MyComponent from '../packages/my-component';
```
#### - Setup scope globally
This is the easiest way to setup scope once for an entire project
```tsx
//.storybook/manager.js
import { addons } from '@storybook/addons';
import { LIVE_EXAMPLES_ADDON_ID } from 'storybook-addon-live-examples';
addons.setConfig({
[LIVE_EXAMPLES_ADDON_ID]: {
scope: {
MyComponent,
},
},
});
```
```tsx
Now, you can use MyComponent in all examples
```
#### - Setup scope inside monorepo
This is an example of how you can add all used components and helpers to the scope.
```tsx
// .storybook/scope.ts
import { ComponentType } from 'react';
import * as icons from 'some-icons-pack';
import * as knobs from '@storybook/addon-knobs';
// packages/{componentName}/index.ts
const req = require.context('../packages', true, /^\.\/(.*)\/index.ts$/);
const components = req.keys().reduce((acc: Record, key) => {
Object.entries(req(key)).forEach(([componentName, component]: [string, any]) => {
acc[componentName] = component;
});
return acc;
}, {});
export default {
...components,
...icons,
...knobs,
};
// .storybook/manager.js
import scope from './scope';
addons.setConfig({
[LIVE_EXAMPLES_ADDON_ID]: {
scope,
},
});
```
Typescript supported
## Getting started
### 1. Install addon
```bash
TODO
```
### 2. Register addon in main.js
```js
module.exports = {
addons: ['storybook-addon-live-examples'],
};
```
### 3. Setup addon in preview.js (optional step)
```js
import { addons } from '@storybook/addons';
import { LIVE_EXAMPLES_ADDON_ID } from 'storybook-addon-live-examples';
import theme from 'prism-react-renderer/themes/github';
import AllComponents from '../packages';
addons.setConfig({
[LIVE_EXAMPLES_ADDON_ID]: {
// custom theme from prism-react-renderer (optional)
editorTheme: theme,
// internationalization (optional)
copyText: ['Copy', 'Copied'],
expandText: ['Show code', 'Hide code'],
shareText: ['Share', 'Shared'],
// scope (globally accessible components & functions) (optional)
scope: {
...AllComponents,
someFunction: () => 42
},
},
});
```
### 4. Configure webpack (for storybook 7 only)
```js
const { patchWebpackConfig } = require('storybook-addon-live-examples/dist/cjs/utils');
module.exports = {
webpackFinal: (config) => {
patchWebpackConfig(config);
return config;
}
};
```
## Usage
### CSF
Live examples will be rendered instead of the default addon-docs canvas.
Your can customize examples by parameters:
```tsx
export default {
title: 'Components/Button',
parameters: {
scope: {
scopeValue,
},
}
};
const scopeValue = 42;
export const Primary = () => ;
Primary.parameters = {
expanded: true
};
export const Secondary = () => ;
```
**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**
```markdown
|```tsx live
|