How to Create a Component Library with Storybook and Stencil

Tools Used Throughout The Article 💭

• Storybook 7
• Stencil
• Yarn 3
• React
• TypeScript

So, What Is Stencil ? ⚡

Why Would You Use Stencil Over Other Tools? 🤷🏼

1. Framework Agnostic 🔁

2. Performance 🚤

3. Standards Compliant 🗃️

4. Ease of Use 🎗️

5. Flexibility and Customization 🎨

What is Storybook ? 🤔

Why Use Storybook For A Project? 🤷🏼

1. Enhanced Collaboration 👬

• Developers : It allows them to work on one component at a time without worrying about the entire application's state. This modularity makes it easier to debug and test components.

• Designers : They can easily review how different components look and feel, making it easier to maintain design consistency across the application.

• Product Managers : They can see all the components in one place, which makes it easier to understand what is available and how it can be combined to create new features.

• Testers: Storybook provides a unified platform where testers can easily interact with individual components in isolation, making it simpler to conduct unit and integration tests.

2. UI Version Control 🛂

3. Embed Stories 📜

4. Rapid Prototyping 🎨

5. Autodocs 📝

Storybook Auto-docs generates documentation automatically based on component stories. It captures props tables, usage docs, and code samples without additional effort.

AutoDocs is configured through doc blocks in Storybook's MDX files or in a custom template file for automatic documentation.

Developers write stories once and get comprehensive docs for free. This reduces duplication and keeps docs synchronized. Auto-docs helps produce consistent interactive documentation with less manual work.

Storybook add-ons 💢

1. addon cssprops 👩🏼‍🎨

• 🚪 Local variables : These are defined in a Storybooks story and are available to that story by default. For example, you may define default font sizes, colors, etc :

.ui-button {
	background: var(--ui-custom-button-color, var(--ui-button-color, var(--ui-button-color))); 
}

parameters: {
    cssprops: {
      'ui-custom-button-color': { value: 'rgb(0, 169, 79)', control: 'color', description: 'color of the page' }
    },
  }

• 🪟 Service-side variables : These are imported into a specific story from an external CSS variables library through css variables. This allows sharing common variables across different components and stories.

.ui-button {
	background: var(--ui-custom-button-color, var(--ui-button-color, var(--ui-button-color))); 
}

2. addon a11y

3. addon essentials

• @storybook/addon-actions : Logs actions like clicks, hovers, keypresses to the actions panel for debugging. Automatically infers action names from event handlers.

• @storybook/addon-backgrounds : Allows setting backgrounds on the preview to style components in different states. Supports gradients.

• @storybook/addon-controls : Automates prop controls generation from component args/props. Supports types like string, number, boolean, object.

• @storybook/addon-docs : Generates documentation pages from MDX, CSF, or automatically from components.

• @storybook/addon-toolbars : Adds extra toolbars like zoom, grid layout, fullscreen.

• @storybook/addon-viewport : Responsive testing with a toolbar to set viewport sizes.

• @storybook/addon-measure : Inspect size and position of elements.

What is Storybooks Chromatic 🔁

• Effortless Visual Reviews : With Chromatic, designers and product managers can scrutinize UI changes directly in the web browser, eliminating the need to pull source code or set up the application. This accelerates the feedback loop and simplifies the approval process.

• Automated Visual Consistency Checks : Developers can take advantage of Chromatic's visual regression tests to ensure that any new modifications don't inadvertently affect existing components. This helps in maintaining a consistent and reliable UI.

• Easy Sharing for Remote Teams : Chromatic makes the updated UI components accessible to the team via a simple shared link, making it an invaluable tool for distributed teams.

Storybook and Cypress for End-to-End Testing ⌛

• Interaction Testing : Simulate real-world user interactions within Storybook, like clicks or form submissions, to ensure components behave as expected.

• Accessibility Checks : Run automated tests to confirm your components meet accessibility standards, making your application more inclusive.

• Snapshot Verifications : Capture and compare component states to identify visual changes, streamlining the QA process for visual regression testing.

• Streamlined Development : Cypress and Storybook together streamline the development process, making it easier for teams to collaborate.

• Automated Testing : Cypress provides automated end-to-end testing, ensuring each component functions as intended.

• Component Isolation : Storybook allows for isolated component development and testing, making it easier to spot issues.

• Real-Time Testing : The integration enables real-time testing, allowing for immediate feedback and quicker iterations.

• Quality Assurance : This combination improves code quality and ensures a consistent user experience, reducing the risk of bugs making it to production.

Building Components with Storybook and Stencil 🚀

Initialize Stencil Project ⬇️

# install stencil in your local machine
yarn global add stencil

# create a stencil project 
yarn create stencil

Creating Atomic Components ⚛️

Atom : The ui-button 🔘

import { Component, Host, Prop, h } from '@stencil/core';

@Component({
  tag: 'ui-button',
  styleUrl: 'ui-button.scss',
  shadow: true,
})

export class UiButton {
  @Prop() text: string;

  render() {
    return (<Host><button>{(this.text || '')}</button></Host>);
  }
}

:host {
  display: block;
}

button {
  padding: 10px;
  border: 1px solid black;
  border-radius: 30px;
  background-color: var(--ui-custom-button-color, var(--ui-button-color, var(--ui-button-color)));
  color: white;
}

 Molecule : A ui-card ✉️

import { Component, Host, Prop, h } from '@stencil/core';

@Component({
  tag: 'ui-card',
  styleUrl: 'ui-card.scss',
  shadow: true,
})

export class UiCard {
  @Prop() text: string;

  render() {
    return (<Host>
      <div class="ui-card">
        <div class="ui-card__header">
					{(this.text || '')}
				</div>
        <div class="ui-card__action">
					<slot name="action" v-bind="scope" />
				</div>
      </div>
    </Host>);
  }
}

:host {
  display: block;
}

.ui-card {
  background-color: var(--ui-custom-card-color, var(--ui-card-color, var(--ui-card-color)));
  width: fit-content;
  border-radius: 10px;
  padding: 10px;

  &__header {
    color: white;
    padding: 10px;
  }

  &__action {
    padding: 10px 0;
  }
}

Organism : The ui-home 🏡

import { Component, Host, Prop, h } from '@stencil/core';

@Component({
  tag: 'ui-home',
  styleUrl: 'ui-home.scss',
  shadow: true,
})

export class UiHome {
  @Prop() text: string;

  render() {
    return (<Host>
      <div class="ui-home">
        <div class="ui-home__header">
          {(this.text || '')}
        </div>
        <div class="ui-home__content">
          <slot name="content" v-bind="scope" />
        </div>
      </div>
    </Host>);
  }
}

:host {
  display: block;
}

.ui-home {
  background: var(--ui-custom-home-color, var(--ui-home-color, var(--ui-home-color)));
  padding: 10px;

  &__header {
    color: white;
  }

  &__content {
    padding: 10px;
  }
}

Installing Storybook 🪄

# move to your project directory
cd project-name

# install storybook to your project 
yarn dlx sb@next init --type html

Configuring Storybooks Add-ons, Build & Documentation ⚙️

# install all addons needed
yarn add -D @storybook/addon-essentials @storybook/addon-a11y @ljcl/storybook-addon-cssprops

• A stories array to declare where to find the stories in the project.
• A static directory array to declare public directories.
• A typescript object to add typescript based configurations.
• An add-ons array to include CSS props, A11y and essentials.
• A docs object to allow MDX/TSX.
• WebPack configurations for aliases.
• Babel Loaders to allow TSX.

const path = require("path");

module.exports = {
  stories: ["../src/**/*.stories.mdx", "../src/**/*.stories.@(js|jsx|ts|tsx)"],
  staticDirs: ["../public"],
  typescript: { reactDocgen: "react-docgen", skipBabel: true, check: false },

  addons: [
    "@ljcl/storybook-addon-cssprops",
    "@storybook/addon-a11y",
    "@storybook/addon-essentials"
  ],

  docs: { autodocs: "tag", defaultName: "readme" },

  framework: { name: "@storybook/html-webpack5", options: {} },

  webpackFinal: async (config, { configType }) => {
    config.resolve.alias = {
      ...config.resolve.alias,
      "@": path.resolve(__dirname, "../src"),
    };

    config.module.rules.push({
      test: /\.(ts|tsx)$/,
      loader: require.resolve("babel-loader"),
    });

    config.resolve.extensions.push(".ts", ".tsx");
    return config;
  },
};

Configuring Storybook with preview.tsx

export const parameters = {
  actions: { argTypesRegex: "^on[A-Z].*" },
  backgrounds: { default: 'light' },

  controls: {
    expanded: true,
    matchers: {
      color: /(background|color)$/i,
      date: /Date$/,
    },
  },

  options: {
    hierarchySeparator: /\//,
    hierarchyRootSeparator: '|',
    storySort: {
      method: 'alphabetical',
      order: [ 'intro', [ 'organism', 'molecule', 'atom' ],
      locales: 'en-US',
    },
  },

  docs: {
    toc: {
      headingSelector: 'h1, h2, h3',
      ignoreSelector: '#primary',
      title: 'table of contents',
      disable: false,
      unsafeTocbotOptions: {
        orderedList: false,
      },
    },
  },
}

Adding Stories for your Stencil Components 🌟

import { h } from 'jsx-dom';
import { action } from '@storybook/addon-actions';

export default {
  title: 'stories/atom/UiButton',
  tags: ['autodocs'],
  argTypes: {
    text: {
      control: 'text',
      description: 'text of the button',
      type: { summary: 'string' },
      defaultValue: { summary: 'select' },
    }
  },
  args: {
    text: 'select',
  },
  parameters: {
    cssprops: {
      'ui-custom-button-color': { value: 'rgb(0, 169, 79)', control: 'color', description: 'color of the page' }
    },
  },
};

const Template = (args) => (
  <ui-button text={args.text} onClick={() => action('button-select')(args.text)} />
);

export const UiButton = Template.bind({});

import { h } from "jsx-dom";
import { action } from "@storybook/addon-actions";

export default {
  title: "stories/molecule/UiCard",
  tags: ["autodocs"],
  argTypes: {
    text: {
      control: "text",
      description: "text of the card",
      type: { summary: "string" },
      defaultValue: { summary: "card" },
    },
  },
  args: {
    text: "card",
  },
  parameters: {
    cssprops: {
      "ui-custom-card-color": {
        value: "rgb(109, 118, 178)",
        control: "color",
        description: "color of the card",
      },
    },
  },
};

const Template = (args) => (
  <ui-card text={args.text}>
    <ui-button
      slot="action"
      text="select"
      onClick={() => action("button-select")(args.text)}
    />
  </ui-card>
);

export const UiCard = Template.bind({});

import { h } from "jsx-dom";
import { action } from "@storybook/addon-actions";

export default {
  title: "stories/organism/UiHome",
  tags: ["autodocs"],
  argTypes: { text: { type: { summary: "string" }, description: "text of the header", defaultValue: { summary: "header text" }, control: "text", }, },
  args: { text: "header text", },
  parameters: { cssprops: { "ui-custom-home-color": { value: "rgb(224, 224, 224)", control: "color", description: "color of the page", }, }, },
};

const Template = (args) => (
  <ui-home text={args.text}>
    <ui-card slot="content" text="card text">
      <ui-button slot="action" text="select" onClick={() => action("button-select")(args.text)} />
    </ui-card>
  </ui-home>
);

export const UiHome = Template.bind({});

Exporting The Library with Multi-Framework Support 🦑

The Configuration File 🛠️

// stencil.config.ts

import { Config } from "@stencil/core";
import { sass } from "@stencil/sass";
import { vueOutputTarget } from "@stencil/vue-output-target";
import { angularOutputTarget } from "@stencil/angular-output-target";
import { reactOutputTarget } from "@stencil/react-output-target";

export const config: Config = {

  namespace: 'storybook-stencil',
  outputTargets: [

		// generates a dist directory with ECMAScript modules.
    { type: "dist", esmLoaderPath: "../loader" },

		// creates custom elements in the dist directory.
    { type: "dist-custom-elements" },

		// generates README documentation.
    { type: "docs-readme" },

    // builds a www directory but without service workers.
    { type: "www", serviceWorker: null },

    // exports components as Vue components.
    vueOutputTarget({
      componentCorePackage: "storybook-stencil",
      proxiesFile: "./lib/vue/components.ts",
    }),

		// exports components as Angular components and directives.
    angularOutputTarget({
      componentCorePackage: "storybook-stencil",
      directivesProxyFile: "./lib/angular/components.ts",
      directivesArrayFile: "./lib/angular/directives.ts",
    }),

		// exports components as React components.
    reactOutputTarget({
      componentCorePackage: "xotoboil-storybook-stencil",
      proxiesFile: "./lib/react/index.ts",
      includeDefineCustomElements: true,
    }),
  ],

	// adds scss accessible by all components.
  plugins: [
    sass({
      injectGlobalPaths: ["src/styles/index.scss"],
    }),
  ],
};

• Vue components via vueOutputTarget
• Angular components/directives via angularOutputTarget
• React components via reactOutputTarget

The Output Directory : dist 📦

dist/
├── custom-elements
├── loader
├── storybook-stencil.js
├── collection
└── types

Preview Your Components 🏃🏽‍♂️

# run your storybook library
yarn storybook

In Conclusion 🔥