Storybook

Storybook (opens in a new window) is a developer tool for authoring components in isolation with interactive demonstrations and documentation. This guide will give a high level overview of setting up Storybook and integrating with any Greenwood specific features.

You can see an example (this website's own repo!) here (opens in a new window).

Setup

This guide assumes Storybook v10+

We recommend using the Storybook CLI (opens in a new window) to setup a project from scratch using the Web Components template:

# npm requires a -- between arguments
$ npm create storybook@latest -- --type web_components

See our Vitest docs for additional configuration examples to support Import Attributes and Greenwood resource plugins usage in your components. For that guide, you'll be updating a vite.config.js file instead.

Usage

You should now be good to start writing your first story! 📚

export default class Footer extends HTMLElement {
  connectedCallback() {
    this.innerHTML = `
      <footer>
        <h4>Greenwood</h4>
        <img src="/assets/my-logo.webp" />
      </footer>
    `;
  }
}

customElements.define("app-footer", Footer);

import { html } from 'lit';
import './footer.js';

const meta = {
  title: 'Components/Footer',
};

export default meta;

export const Primary = () => {
  return html`<app-footer></app-footer>`;
};

Static Assets

To help with resolving any static assets used in your stories, you can configure staticDirs (opens in a new window) to point to your Greenwood workspace.

const config = {
  staticDirs: ["../src"],
};

export default config;

PostCSS

If you are using Greenwood's PostCSS plugin, you'll need to create a secondary CommonJS compatible configuration file for Storybook.

So if your current postcss.config.js looks like this:

export default {
  plugins: [(await import("tailwindcss")).default, (await import("autoprefixer")).default],
};

You'll want to create a CommonJS version with the following name, depending on which version of Storybook you are using:

• Storybook >= 8 - postcss.config.cjs
• Storybook <= 7 - .postcssrc.js

module.exports = {
  plugins: [require("tailwindcss"), require("autoprefixer")],
};

Content as Data

If you are using any of Greenwood's Content as Data Client APIs, you'll want to configure Storybook to mock the HTTP calls Greenwood's data client makes, and provide the desired response needed based on the API being called.

This can be accomplished with the storybook-addon-fetch-mock (opens in a new window) addon and configuring it with the right matcher.url and matcher.response.

Be aware of this open issue (opens in a new window) with storybook-addon-fetch-mock.

1. First, install the storybook-addon-fetch-mock addon

   npm i -D storybook-addon-fetch-mock
   

   yarn add storybook-addon-fetch-mock --save-dev
   

   pnpm add -D storybook-addon-fetch-mock
   

2. Then add it to your .storybook/main.js configuration file as an addon

   const config = {
     addons: ["storybook-addon-fetch-mock"],
   };
   
   export default config;
   

3. Then in your story files, configure your Story to return mock data

   import "./blog-posts-list.js";
   import pages from "../../stories/mocks/graph.json";
   
   export default {
     parameters: {
       fetchMock: {
         mocks: [
           {
             matcher: {
               url: "http://localhost:1984/___graph.json",
               response: {
                 // this is an example of mocking out getContentByRoute
                 body: pages.filter((page) => page.route.startsWith("/blog/")),
               },
             },
           },
         ],
       },
     },
   };
   
   const Template = () => "<app-blog-posts-list></app-blog-posts-list>";
   
   export const Primary = Template.bind({});
   

To quickly get a "mock" graph to use in your stories, you can run greenwood build and copy the graph.json file from the build output directory.