demoing-storybook

Demoing via storybook

For demoing, documenting and showcasing different states of your Web Component, we recommend using storybook.

::: tip This is part of the default open-wc recommendation :::

Features

• Create API documentation/playground
• Use Storybook docs mode to showcase your elements within the normal text flow
• Works down to IE11
• Prebuilt storybook UI (for a fast startup)
• Uses es-dev-server (serve modern code while developing)
• Completely separate storybook UI from your code

Prebuilt Storybook comes with

• @storybook/web-components
• @storybook/addon-a11y
• @storybook/addon-actions
• @storybook/addon-backgrounds
• @storybook/addon-console
• @storybook/addon-docs
• @storybook/addon-links
• @storybook/addon-knobs
• @storybook/addon-viewport
• storybook-addon-web-components-knobs

Demo

::: tip Don't take our word for it but look at the documentation of a demo card and the documentation of the knobs decorator. :::

Setup

npm init @open-wc
# Upgrade > Demoing

Manual

• yarn add @open-wc/demoing-storybook --dev
• Copy at minimum the .storybook folder to .storybook
• If you want to bring along the examples, you may also copy the stories folder.
• Be sure you have a custom-elements.json file.
• Add the following scripts to your package.json

"scripts": {
  "storybook": "start-storybook --node-resolve --watch --open",
  "storybook:build": "build-storybook"
},

Migration

If you are already using @open-wc/storybook be sure to check out the Migration Guide.

Usage

Create documentation/stories within the stories folder.

npm run storybook

CLI configuration

Storybook specific

name	type	description
stories	string	A glob which stories to include. Be sure to wrap it in '. Default: './stories/\*.stories.{js,mdx}'
config-dir	string	Where the storybook config files are. Default: ./.storybook
		Build only
output-dir	string	Rollup build output directory. Default: ./static-storybook

Dev server

The storybook server is based on es-dev-server, see the docs of the dev server for any additional command options.

Create documentation

Create a *.stories.mdx (for example card.stories.mdx) file within the stories folder.

import { Story, Preview, Meta, Props } from '@open-wc/demoing-storybook';
import { html } from 'lit-html';
import '../demo-wc-card.js';

<Meta title="Card|Docs" />

# Demo Web Component Card

A component meant to display small information with additional data on the back.
// [...] use markdown to format your text

<Preview withToolbar>
  <Story name="Simple" height="220px">
    {html`
      <demo-wc-card>Hello World</demo-wc-card>
    `}
  </Story>
</Preview>

## API

The api table will show the data of "demo-wc-card" in your `custom-elements.json`.

<Props of="demo-wc-card" />

// [...]

Create stories in CSF (Component story format)

Create a *.stories.js (for example card-variations.stories.js) file within the stories folder.

export default {
  title: 'Card|Variations',
  component: 'demo-wc-card',
};

export const singleComponent = () => html`
  <demo-wc-card></demo-wc-card>
`;

For more details see the official storybook docs.

You can import these templates into any other place if needed.

For example in tests:

import { expect, fixture } from '@open-wc/testing';
import { singleComponent } from '../stories/card-variations.stories.js';

it('has a header', async () => {
  const el = await fixture(singleComponent);
  expect(el.header).to.equal('Your Message');
});

Create API playground

::: tip You can find a more interactive version of this in the withWebComponentsKnobs docs. :::

Base on the data in custom-elements.json we can automatically generate knobs for your stories.

To enable this feature you will need to add an additional decorator.

MDX

import { withKnobs, withWebComponentsKnobs } from '@open-wc/demoing-storybook';

<Meta
  title="WithWebComponentsKnobs|Docs"
  decorators={[withKnobs, withWebComponentsKnobs]}
  parameters={{ component: 'demo-wc-card', options: { selectedPanel: 'storybookjs/knobs/panel' } }}
/>

<Story name="Custom Header" height="220px">
  {html`
    <demo-wc-card header="Harry Potter">A character that is part of a book series...</demo-wc-card>
  `}
</Story>

CSF

import { html } from 'lit-html';
import { withKnobs, withWebComponentsKnobs } from '@open-wc/demoing-storybook';

import '../demo-wc-card.js';

export default {
  title: 'Card|Playground',
  component: 'demo-wc-card',
  decorators: [withKnobs, withWebComponentsKnobs],
  parameters: { options: { selectedPanel: 'storybookjs/knobs/panel' } },
};

export const singleComponent = () => html`
  <demo-wc-card></demo-wc-card>
`;

For additional features like

• define which components to show knobs for
• showing knobs for multiple different components
• syncing components states to knobs
• Filtering properties and debugging states

please see the official documentation of the knobs for web components decorator.

custom-elements.json

In order to get documentation for web-components you will need to have a custom-elements.json file. You can hand write it or better generate it. Depending on the web components sugar you are choosing your mileage may vary. Please not that the details of the file are still being discussed so we may adopt to changes in custom-elements.json without a breaking release.

Known analyzers that output custom-elements.json:

• web-component-analyzer
  • Supports LitElement, Polymer, Vanilla, (Stencil)
• stenciljs
  • Supports Stencil (but does not have all metadata)

It basically looks like this:

{
  "version": 2,
  "tags": [
    {
      "name": "demo-wc-card",
      "properties": [
        {
          "name": "header",
          "type": "String",
          "description": "Shown at the top of the card"
        }
      ],
      "events": [],
      "slots": [],
      "cssProperties": []
    }
  ]
}

For a full example see the ./demo/custom-elements.json.

Additional middleware config like an api proxy

As we are using es-dev-server under the hood you can use all it's power. You can use the regular command line flags, or provide your own config via start storybook -c /path/to/config.js.

To set up a proxy, you can set up a koa middleware. Read more about koa here.

const proxy = require('koa-proxies');

module.exports = {
  port: 9000,
  middlewares: [
    proxy('/api', {
      target: 'http://localhost:9001',
    }),
  ],
};

<script> export default { mounted() { const editLink = document.querySelector('.edit-link a'); if (editLink) { const url = editLink.href; editLink.href = url.substr(0, url.indexOf('/master/')) + '/master/packages/building-storybook/README.md'; } } } </script>