Storybook Addon Azure Devops Plugin

Link stories to Azure Devops work items

Installation

First, install the package.

npm install --save-dev sb-azure-devops

Then, register it as an addon in .storybook/main.js.

// .storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';

const config: StorybookConfig = {
  // ...rest of config
  addons: [
    '@storybook/addon-essentials'
    'sb-azure-devops', // 👈 register the addon here
  ],
};

export default config;

Usage

Environment variables

You first need to generate a personal access token for Azure Devops. To do so follow the instructions from Microsoft. The minimum permissions that are needed are:

• Work items, read

For security your Azure Devops personal access token is read as an environment variable. After generating your access token you can add the token to your environment variables using the key "AZURE_DEVOPS". Depending on the system you're running your Storybook instance on there are different ways to add environment variables, here are some common ways:

• Local
  • Local, Windows
  • Local, Mac
• Hosted
  • Netlify
  • Vercel
  • Azure

Storybook parameters

Azure devops Organisation and Project values must be defined as auzreDevops.org and auzreDevops.project parameters in the initial globals. These are defined in the preview.js|ts file. If your Storybook implementation needs to support multiple projects/organisations, these can be handled by setting up global options to switch Organisation and Projects.

// preview.ts

// Replace your-framework with the name of your framework
import type { Preview } from "@storybook/your-framework";

const preview: Preview = {
  // ...rest of config
  initialGlobals: {
    // ...rest of initial globals config
    azureDevops: {
      org: "devopsOrgName", // Azure Devops organisation name
      project: "devopsProjectName", //Project inside of Azure devops
      key: import.meta.env.AZURE_DEVOPS || process?.env?.AZURE_DEVOPS //Environment variable containing Azure Devops security key
    }
  },
};

You can then associate work item ids from azure devops with your stories by adding an array of ids as strings to your story parameters

// Button.stories.ts

// Replace your-framework with the name of your framework
import type { Meta } from '@storybook/your-framework';

import { Button } from './Button';

const meta: Meta<typeof Button> = {
  component: Button,
  parameters: {
    workItems: ["1", "2"]
  }
};

export default meta;

Listing work items in docs (MDX)

The addon also exports a WorkItemsList React component you can embed in your MDX docs pages to render every Azure Devops work item associated with a stories file. It reads the same workItems parameter from each story and the azureDevops global for connection details, then fetches each item's title, type, state and icon for display (linked back to Azure Devops).

{/* Button.mdx */}
import { Meta } from '@storybook/addon-docs/blocks';
import { WorkItemsList } from 'sb-azure-devops';
import * as ButtonStories from './Button.stories';

<Meta of={ButtonStories} />

# Button

<WorkItemsList of={ButtonStories} />

Props:

• of (optional) — a reference to a stories file (its meta/default export) or a single story. When omitted, work items are collected from every story on the current docs page.
• title (optional) — heading rendered above the list.

@storybook/addon-docs (bundled with @storybook/addon-essentials) must be present to use this component.

Releases

• 2.0.1 - Bug fixes
• 2.0.0 - Support for Storybook 10
  • Add list of work items to mdx
• 1.0.0 - Support for Storybook 9
• 0.0.2 - Bug fixes.
  • Moving location where key is set in globals
• 0.0.1 - Initial public release.
  • Read only work items from Azure Devops.
  • Configure which fields you want to display in your work items.
  • Supports light and dark mode.
  • Supports horizontal and vertical addon layouts.