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

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

npx storybook@latest init

As part of the prompts, we suggest the following answers to project type (web_components) and builder (Vite):

✔ Do you want to manually choose a Storybook project type to install? … yes
? Please choose a project type from the following list: › - Use arrow-keys. Return to submit.
  ↑ webpack_react
    nextjs
    vue3
    angular
    ember
❯   web_components
    html
    qwik
    preact
  ↓ svelte

We were not able to detect the right builder for your project. Please select one: › - Use arrow-keys. Return to submit.
❯   Vite
    Webpack 5

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 "./footer.js";

export default {
  title: "Components/Footer",
};

const Template = () => "<app-footer></app-footer>";

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

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

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.