Setup Storybook in a Stencil project was not as easy as I expected. So I documented here the main steps I took to setup my project. Hope this can be useful to others in need.

Beginning with a Stencil application created, run the init script for the Storybook:

npx -p @storybook/cli sb init --type=html

This asks to set up using Webpack 5 or Vite. Both seem to work fine.

Now we need to allow Storybook to run my web components created with Stencil, So inside the .storybook/preview.js add the following code:

import { defineCustomElements } from '../loader';

defineCustomElements();

This will allow us to use the tag created for our components inside the Storybook. Also in this file, you can import the Stencil's global.css file:

import '../src/global/global.css';

Now the basis of the setup is almost done. but there is one small problem. This loader folder that we imported does not exist yet. This folder is created at the build time of our application

so to create this folder we can run the build on watch mode:

npx stencil build --watch

this way every change that we in our components will reflect on the Storybook file (keep in mind that sometimes you need to refresh the Storybook page, especially with CSS).

Now with the Stencil build running, we can start the Storybook in a new terminal tab with the command:

npm run storybook

Great. now we can write our first story. Like with every other Storybook setup, we can place our .stories file into any folder that we want. I like to keep my stories in the same folder as my component, but you are free to follow other structures.

The story should be written using pure HTML into a string (for now at least). So my first story looked like this:

export default {
  title: 'Atoms/Button',
  tags: ['autodocs'],
  argTypes: {
    label: { control: 'text' },
    size: {
      options: ['small', 'medium', 'large'],
      control: { type: 'radio' },
    },

  },
};

const Template = args => `<my-button label="${args.label}" variant="${args.variant}" size="${args.size}"></my-button>`;

export const primary = Template.bind({});
primary.args = {
  label: 'Click me',
  variant: 'primaryFilled',
  size: 'medium',
};

This works fine, but we can set up the JSX syntax pretty easily. So all we need to do is to set up Babel to handle this for us. So first we need to install some libs:

npm i --save-dev @babel/plugin-syntax-jsx @babel/plugin-transform-react-jsx jsx-dom

Now add the plugins we just installed to the .babelrc file on the root of our project:

  "plugins": [
    "@babel/plugin-syntax-jsx",
    [
      "@babel/plugin-transform-react-jsx",
      {
        "pragma": "h"
      }
    ]
  ]

now at our story, we can use the JSX syntax just by importing the h from the jsx-dom library.

import { h } from 'jsx-dom';

export default {
  title: 'Atoms/Button',
  tags: ['autodocs'],
  argTypes: {
    label: { control: 'text' },
    size: {
      options: ['small', 'medium', 'large'],
      control: { type: 'radio' },
    },
  },
};

const Template = args => <plx-button label={args.label} variant={args.variant} size={args.size}></plx-button>;

export const primary = Template.bind({});
primary.args = {
  label: 'Click me',
  variant: 'primaryFilled',
  size: 'medium',
};

much better. The last thing that I struggle with was setting up the events to show up in the actions tab on the Storybook page. The way I did this was to set up the withActions decorator from the @storybook/addon-actions package. So first, to install run this command:

npm i -D @storybook/addon-actions

and then we can use it like this:

export default {
  title: 'Atoms/Button',
  tags: ['autodocs'],
  argTypes: {
    // ...
  },
  decorators: [withActions],

  parameters: {
    actions: {
      handles: ['click', 'mouseover', 'mouseout'],
    },
  },
};

Now the events click, mouseover, and mouseout is logged into the Storybook. Exactly as expected.

Now we have a basic setup of Storybook in a Stencil build. Now you can keep enhancing this setup by adding more plugins to fit your need.