Tilted sphere with longitudinal stripes Modern Web Guides Docs Blog

Plugins: Storybook

This project is currently in alpha. Expect updates and breaking changes.

Plugin for using Storybook with Web Dev Server using es modules.

How it works

This plugin uses an opinionated build of Storybook, making it possible to use it with native es modules and buildless workflows.

This build installs a default set of addons:

  • Actions
  • Backgrounds
  • Controls
  • Docs
  • Viewport
  • Toolbars

It's not possible to install other addons at the moment.


Install the package:

npm i --save-dev @web/dev-server-storybook

Add the plugin and set the project type. See below for supported project types.

import { storybookPlugin } from '@web/dev-server-storybook';

export default {
  plugins: [storybookPlugin({ type: 'web-components' })],

Add a .storybook/main.js file:

module.exports = {
  stories: ['../stories/**/*.stories.@(js|jsx|ts|tsx)'],

Add a story: stories/MyButton.stories.js:

export default {
  title: 'Example/Button',
  argTypes: {
    backgroundColor: { control: 'color' },

const Button = ({ backgroundColor = 'white', text }) => {
  return `
    <button type="button" style="background-color: ${backgroundColor}">

export const ButtonA = args => Button(args);
ButtonA.args = {
  text: 'Button A',

export const ButtonB = args => Button(args);
ButtonB.args = {
  text: 'Button B',

Follow the regular storybook docs to learn how to create stories.


This plugin supports docs written using the storybook MDX format. To import doc blocks, import them from the prebuilt:

Regular storybook:

import { Meta, Story, Canvas, ArgsTable } from '@storybook/addon-docs/blocks';

Storybook prebuilt:

import { Meta, Story, Canvas, ArgsTable } from '@web/storybook-prebuilt/addon-docs/blocks.js';

Follow the regular storybook docs to learn how to create docs.


Project types

We currently supported preact and web-components project types. This corresponds to the Storybook "Framework".

Other project types could be supported, let us know if you are interested in this.


We read a .storybook/preview.js file like regular storybook.

Customizing storybook directory

You can customize the storybook directory when instantiating the plugin:

import { storybookPlugin } from '@web/dev-server-storybook';

export default {
  plugins: [storybookPlugin({ type: 'web-components', configDir: 'custom-directory' })],

Production build

You can run a build on your storybook demo before shipping it to production. Regular storybook uses webpack, which might require considerable configuration to make it work for the buildless storybook. To keep the build simple we are using Rollup.

Running a build

To run a production build, execute the build-storybook command. This takes a few parameters:

config-dirstringDirectory to read storybook config from. defaults to .storybook
output-dirstringDirectory to write the build output to. defaults to storybook-static
typestringProject type. Defaults to web-components

Customizing the build

You can customize the rollup config from your main.js config:

const pluginA = require('rollup-plugin-a');
const pluginB = require('rollup-plugin-b');

module.exports = {
  rollupConfig(config) {
    // add a new plugin to the build

    // use unshift to make sure it runs before other plugins

    return config;