Zeplin CLI Storybook Plugin

Zeplin CLI plugin to generate Storybook links for Zeplin components, inspired by chromatic-cli.

Contents

• Installation
• Usage
  • Remote Storybook instance
  • Local Storybook instance
    • npm script
    • Custom command
  • Matching components with stories
  • URL format for manual matching
  • Use manual matching without connecting a working Storybook
  • Fast fail on Storybook errors
  • Generate DocsPage hyperlinks
  • Ignore SSL certificate errors
  • Using Basic Authentication
• About Connected Components

Installation

Install the plugin using npm.

npm install -g @zeplin/cli-connect-storybook-plugin

Usage

Since Zeplin CLI Storybook Plugin requires a running Storybook instance to collect information about stories, configure the plugin in your components configuration file (.zeplin/components.json) to point to an instance.

Remote Storybook instance

Provide the URL of a remote Storybook instance.

{
    ...
    "plugins" : [{
        "name": "@zeplin/cli-connect-storybook-plugin",
        "config": {
            "url": "<protocol>://<hostname>:<port>", // Defaults to http://localhost:6006
        }
    }],
    ...
}

Local Storybook instance

Zeplin CLI Storybook Plugin can also start a local Storybook instance to collect information about stories. You can either provide an npm script or a custom command to start a Storybook instance.

npm script

Provide the name of the npm script to start a Storybook instance.

{
    ...
    "plugins" : [{
        "name": "@zeplin/cli-connect-storybook-plugin",
        "config": {
            "url": "http://localhost:<port>", // Defaults to http://localhost:6006
            "startScript": "<name of the npm script>"
        }
    }],
    ...
}

Custom command

Provide a custom command to run to start a Storybook instance.

{
    ...
    "plugins" : [{
        "name": "@zeplin/cli-connect-storybook-plugin",
        "config": {
            "url": "http://localhost:<port>", // Defaults to http://localhost:6006
            "command": "<the command to start storybook server>"
        }
    }],
    ...
}

☝️ For all alternatives, the generated hyperlinks in Zeplin will be based on the url property you define.

{
    ...
    "plugins" : [{
        "name": "@zeplin/cli-connect-storybook-plugin",
        "config": {
            "url": "http://localhost:<port>", // Defaults to http://localhost:6006
            "startScript": "<the command to start storybook server>",
            "targetUrl": "<protocol>://<hostname>:<port>"
        }
    }],
    ...
}

☝️ You can use optional targetUrl parameter to generate the hyperlinks to a remote Storybook

Once the Storybook instance is configured, run CLI connect command.

zeplin connect

Matching components with stories

Zeplin CLI Storybook Plugin automatically attempts to match components with stories following these rules:

• For React, resolve component stories by matching the file path in the components configuration file.
• If component property of stories are set (either using CSF or storiesOf API), resolve component stories by matching component property of the stories with component file names, e.g. Avatar.jsx and Avatar.
• Resolve stories by matching story display names (e.g. Design System/Avatar and Avatar) with component file names (e.g. Avatar.jsx and Avatar).

It's also possible to match components with stories manually. Set the storybook property components (within the configuration file, .zeplin/components.json) for each component you want to manually match and provide the story kind and name(s).

{
    ...
    "components": [
        {
            "path": "Avatar.jsx",
            "zeplinNames": [
                "avatar loaded",
                "avatar loading"
            ],
            "storybook": {
                "kind": "Design System/Avatar",
                "stories": [
                    "large",
                    "medium",
                    "small"
                ]
            }
        }
    ]
    ...
}

URL format for manual matching

Manually defined component stories will generate hyperlinks using new hyperlinks (for Storybook v5+). In order to generate old style hyperlinks (for Storybook v4) use the following configuration. Next major release will remove to support of old style hyperlinks.

{
    ...
    "plugins" : [{
        "name": "@zeplin/cli-connect-storybook-plugin",
        "config": {
            "url": "http://localhost:6006",
            "startScript": "storybook",
            "format": "old"
        }
    }],
    ...
}

Use manual matching without connecting a working Storybook

Use fetchStories flag to disable connecting and fetching stories from the given URL, so that you can utilize manual configuration to create Storybook hyperlinks. It is recommended to set it false if the plugin cannot match components using the rules mentioned above.

{
    ...
    "plugins" : [{
        "name": "@zeplin/cli-connect-storybook-plugin",
        "config": {
            "url": "https://storybook.example.com",
            "fetchStories": false,
            "format": "new"
        }
    }],
    ...
}

Fast fail on Storybook errors

Set failFastOnErrors parameter to true to abort on any internal errors happened in Storybook. By default, the plugin will try to fetch whatever story it can retrieve from Storybook even if it reports any errors.

{
    ...
    "plugins" : [{
        "name": "@zeplin/cli-connect-storybook-plugin",
        "config": {
            "url": "http://localhost:6006",
            "startScript": "storybook",
            "failFastOnErrors": true
        }
    }],
    ...
}

Generate DocsPage hyperlinks

You can use useDocsPage parameter to generate DocsPage hyperlinks if you use @storybook/addon-docs in your Storybook instance.

{
    ...
    "plugins" : [{
        "name": "@zeplin/cli-connect-storybook-plugin",
        "config": {
            "url": "http://localhost:6006",
            "startScript": "storybook",
            "useDocsPage": true
        }
    }],
    ...
}

Ignore SSL certificate errors

In case you would need to ignore SSL certificate errors:

{
    ...
    "plugins" : [{
        "name": "@zeplin/cli-connect-storybook-plugin",
        "config": {
            "url": "https://storybook.example.com",
            "ignoreSSLErrors": true
        }
    }],
    ...
}

About Connected Components

Connected Components in Zeplin lets you access components in your codebase directly on designs in Zeplin, with links to Storybook, GitHub and any other source of documentation based on your workflow. 🧩

Zeplin CLI uses plugins like this one to analyze component source code and publishes a high-level overview to be displayed in Zeplin.