storybook-addon-stencil

0.2.3 verified Fri May 01 auth: no javascript

A Stencil compiler integration for Storybook (v8). Current stable version 0.2.3, published April 2024. Integrates with @storybook/web-components-vite to transpile Stencil components on the fly, automatically handling custom element definition, dependencies, and HMR. Key differentiators: eliminates need for manual defineCustomElements calls, extracts ArgTypes and Controls from Stencil source, and manages CSS and component imports via Vite plugins. Requires Stencil v4 and Storybook v8. Peer dependency on TypeScript ^5.4.3. Limited adoption; last release over a year ago.

Common errors

error Error: Cannot find module 'storybook-addon-stencil/vite' ↓

cause Only available since v0.2.0; old versions do not export from subpath.

fix

Upgrade to >=0.2.0, or import from 'storybook-addon-stencil' (but only the addon entry point).

error TypeError: e.defineCustomElements is not a function ↓

cause Calling defineCustomElements() in preview.js after the addon already handles it.

fix

Remove defineCustomElements() from .storybook/preview.js.

error Warning: React is not a registered component (or similar React-related error) ↓

cause Using this addon with @storybook/react instead of @storybook/web-components-vite.

fix

Switch framework to '@storybook/web-components-vite' in Storybook config.

error ENOENT: no such file or directory, open '...dist/stencil-output.json' ↓

cause Stencil build output not found; the addon expects a dist directory with Stencil output.

fix

Run stencil build first, or ensure storybook: true in Stencil config for HMR.

Warnings

breaking v0.2.0 dropped support for Stencil v3 and Storybook v7; requires Stencil v4 and Storybook v8. ↓

fix Upgrade Stencil to ^4.0.0 and Storybook to ^8.0.0.

breaking v0.2.0 moved from Webpack to Vite. Existing projects using custom Webpack configs must migrate to Vite. ↓

fix Switch to @storybook/web-components-vite and remove any webpack-related addons.

gotcha Do NOT call defineCustomElements in preview.js; the addon handles it automatically. Doing so can cause double registration errors or broken HMR. ↓

fix Remove defineCustomElements() from .storybook/preview.js.

gotcha All components must be explicitly imported in each story file; the addon does not auto-discover them. ↓

fix Add import './my-component' at the top of each story file for every component used.

deprecated The addon's automatic doc extraction may not work with Storybook's autodocs; manual ArgTypes doc block is recommended. ↓

fix Use <ArgTypes of={Default} /> in MDX files instead of relying on autodocs.

Install

npm install storybook-addon-stencil

yarn add storybook-addon-stencil

pnpm add storybook-addon-stencil

Imports

default (addon registration)

wrong

"storybook-addon-stencil" (string without options object)

correct

{
  name: 'storybook-addon-stencil',
  options: { stencilOptions: {} }
}

stencilVitePlugin

wrong

import { stencilVitePlugin } from 'storybook-addon-stencil'

correct

import { stencilVitePlugin } from 'storybook-addon-stencil/vite'

Vite plugins are exported from a separate subpath; available since v0.2.0

cssVitePlugin

wrong

import { cssVitePlugin } from 'storybook-addon-stencil'

correct

import { cssVitePlugin } from 'storybook-addon-stencil/vite'

Separate Vite plugin for CSS; required alongside stencilVitePlugin for full functionality

Quickstart

Minimal setup to add the addon, register it in Storybook config, and import a Stencil component in a story.

// .storybook/main.js
/** @type { import('@storybook/web-components-vite').StorybookConfig } */
const config = {
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  framework: '@storybook/web-components-vite',
  addons: [
    {
      name: 'storybook-addon-stencil',
      options: {
        stencilOptions: {
          // optional: Stencil transpile options
        },
      },
    },
  ],
};
export default config;

// .storybook/preview.js
// No need to call defineCustomElements here

// stories/MyComponent.stories.js
import './my-component';

export default {
  title: 'MyComponent',
  component: 'my-component', // auto-infers argTypes
};

export const Default = {
  args: {
    'first-prop': 'Hello',
  },
};