Storybook Addon confluence-addon

An addon to implement Confluence documentation in Storybook.

Getting started

Walkthrough Video Tutorial

1. Install

npm install -D addon-confluence

yarn add -D addon-confluence

pnpm add -D addon-confluence

2. Register the addon in `.storybook/main.js and add the staticDirs configuration to serve the 'public' directory."

To ensure that the Confluence documentation is accessible to your Storybook application, you need to configure Storybook to serve the public directory where the fetched documentation is stored.

export default {
  addons: [
    "@storybook/addon-links",
    "@storybook/addon-essentials",
    "addon-confluence", // Add this line to register the addon
  ],
  staticDirs: ["public"], // Add this line to serve the 'public' directory
};

3. Create a token for Confluence!

Go to this link and create an API Token for your account. Then add it along with the email for your account to a .env file as so.

[email protected]
STORYBOOK_CONFLUENCE_TOKEN=YourTokenHere!

4. Add a confluence.js file to your .storybook directory.

The file name must be "confluence.js". This will be the target for the script that fetches the documentation at build time. The default export must be an array of objects with domain and id keys.

const domain = "your-domain";

const confluence = [
  // Add your (domain, id) pairs here
  { domain: domain, id: "4166582285" },
  { domain: domain, id: "4166844417" },
  { domain: "different-domain", id: "4166844418" },
];
// This can be named anything but it must be a default export of an array of objects with `domain` and `id` keys.
export default confluence;

5. Add a confluence ID to your story!

Next, we need add a page id to the story. You can find this within the url while viewing the desired Confluence page. We only need the id for this step but we will need your_domain for the next step.

For example: https://<your_domain>.atlassian.net/wiki//pages/<your_page_id>/Example_Page_Name

Then simply add "confluence" as an object to your story. And then add the id as its property:

export default {
  title: "My stories",
  component: Button,
};

export const myStory = {
  parameters: {
    confluence: {
      id: 12345678,
    },
  },
};

6. Add Scripts to package.json

To ensure that the fetchDocs script runs automatically before building Storybook, you need to update your project’s package.json by adding the prestorybook:build script and ensuring that cross-env is installed. Follow these steps:

Open your project’s package.json file and add the following scripts under the "scripts" section:

{
  "scripts": {
    // ... other scripts
   "prebuild-storybook": "fetchDocs", .// Add this line
    "storybook:build": "cross-env NODE_OPTIONS=--openssl-legacy-provider storybook build",
    // ... other scripts
  }
}

If you have a different build script, prerfix pre to your build script. and set the value to fetchDocs as shown above.

7. Injecting Environment Variables in GitHub Actions

Start by adding a new secret to your GitHub repository. Navigate to your repository on GitHub, click on the "Settings" tab, and then click on "Secrets" in the left-hand sidebar. Click on the "New repository secret" button, and add the following secrets:

• STORYBOOK_CONFLUENCE_EMAIL: The email address associated with your Confluence account.
• STORYBOOK_CONFLUENCE_TOKEN: The API token generated for your Confluence account.

If you are using Chromatic for deployment and need to inject environment variables into your hosted Storybook, update your .github/workflows/chromatic.yml file as follows:

.github/workflows/chromatic.yml
jobs:
  chromatic:
    steps:
      # ... other steps

      - uses: chromaui/action@latest
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
        env:
          # 👇 Sets the environment variable
          STORYBOOK_CONFLUENCE_EMAIL: ${{ secrets.STORYBOOK_CONFLUENCE_EMAIL }}
          STORYBOOK_CONFLUENCE_TOKEN: ${{ secrets.STORYBOOK_CONFLUENCE_TOKEN }}

By adding this configuration, your Storybook environment variables will be correctly injected during the Chromatic deployment process.