@zeplin/cli-connect-storybook-plugin
v2.0.0
Published
Zeplin CLI Connected Components - Storybook Plugin
Downloads
9,715
Keywords
Readme
Zeplin CLI Storybook Plugin
Zeplin CLI plugin to generate Storybook links for Zeplin components, inspired by chromatic-cli.
Contents
- Installation
- Usage
- 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 orstoriesOf
API), resolve component stories by matchingcomponent
property of the stories with component file names, e.g.Avatar.jsx
andAvatar
. - Resolve stories by matching story display names (e.g.
Design System/Avatar
andAvatar
) with component file names (e.g.Avatar.jsx
andAvatar
).
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.