参加在线会议:美国东部时间周四上午 11 点,Storybook 9 发布及 AMA(问我任何事)
文档
Storybook Docs

发布 Storybook

观看视频教程

团队在线发布 Storybook,以便评审和协作进行中的工作。这使得开发者、设计师、产品经理和其他利益相关者无需接触代码或搭建本地开发环境,即可检查 UI 是否正确。

将 Storybook 构建为静态 Web 应用程序

首先,我们需要将 Storybook 构建为静态 Web 应用程序。对于大多数支持的框架,此功能已内置并预配置。在项目根目录中运行以下命令

npm run build-storybook

你可以提供额外的标志来自定义命令。在此处阅读有关标志选项的更多信息。here.

Storybook 将创建一个能够由任何 Web 服务器托管的静态 Web 应用程序。通过运行以下命令在本地预览它

npx http-server ./path/to/build

自定义构建以提升性能

默认情况下,Storybook 的生产构建会将所有 stories 和文档封装到生产包中。这对于小型项目来说是理想的,但对于大型项目或优先考虑缩短构建时间(例如,测试、CI/CD)时可能会导致性能问题。如果需要,你可以在 main.js|ts 配置文件中使用 test 选项自定义生产构建,并调整你的构建脚本以使用 --test 标志启用优化。

npm run build-storybook -- --test

使用 Chromatic 发布 Storybook

将 Storybook 构建为静态 Web 应用程序后,你可以将其发布到你的 Web 主机。我们推荐 Chromatic,这是一个专为 Storybook 构建的免费发布服务,可在云端安全地文档化、版本化和索引你的 UI 组件。

Storybook publishing workflow

开始使用,请使用你的 GitHub、GitLab、Bitbucket 或电子邮件注册,并为你的项目生成一个唯一的 project-token

接下来,从 npm 安装 Chromatic CLI

npm install chromatic --save-dev

包安装完成后,运行以下命令。确保将 your-project-token 替换为你自己的项目 token。

npx chromatic --project-token=<your-project-token>

Chromatic 完成后,你应该已成功部署你的 Storybook。点击提供的链接(即 https://random-uuid.chromatic.com)预览它。

Build 1 published.
 
View it online at https://www.chromatic.com/build?appId=...&number=1.

Chromatic publish build

设置 CI 自动发布

配置你的 CI 环境,以便在你将代码推送到仓库时发布你的 Storybook 并 运行 Chromatic。让我们看看如何使用 GitHub Actions 进行设置。

在你的项目根目录中,在 .github/workflows 目录内添加一个名为 chromatic.yml 的新文件

.github/workflows/chromatic.yml
# Workflow name
name: 'Chromatic Publish'
 
# Event for the workflow
on: push
 
# List of jobs
jobs:
  test:
    # Operating System
    runs-on: ubuntu-latest
    # Job steps
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'yarn'
      - run: yarn
      #👇 Adds Chromatic as a step in the workflow
      - uses: chromaui/action@latest
        # Options required for Chromatic's GitHub Action
        with:
          #👇 Chromatic projectToken,
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          token: ${{ secrets.GITHUB_TOKEN }}

Secrets 是 GitHub 提供的安全环境变量,因此你无需硬编码你的 project-token。阅读 官方文档了解如何配置它们。

提交并推送文件。恭喜你,你已成功自动化 Storybook 的发布。现在,每当你开启一个 PR 时,你都会在 PR 检查中看到一个方便的已发布 Storybook 链接。

PR check publish

与你的团队一起评审

将 Storybook 作为开发过程的一部分发布,可以快速轻松地收集团队反馈。

一个常见的征求评审的方法是将已发布的 Storybook 链接粘贴到拉取请求或 Slack 中。

如果你将 Storybook 发布到 Chromatic,你可以使用 UI Review 功能自动扫描你的 PR 以查找新的和更新的 stories。这使得识别更改并提供反馈变得容易。

UI review in Chromatic

版本控制和历史记录

发布 Storybook 时,你还可以获得组件历史记录和版本控制,精确到每次提交。这在实施评审期间比较不同分支/提交与过去版本的组件时非常有用。

Library history in Chromatic

将 Storybook 发布到其他服务

由于 Storybook 被构建为静态 Web 应用程序,你也可以将其发布到任何 Web 主机,包括 GitHub PagesNetlifyAWS S3 等。但是,组合嵌入 stories、历史记录、版本控制和资产等功能可能需要与 Storybook API 进行更紧密的集成以及安全认证。如果你想了解更多关于头的信息,可以参考迁移指南。此外,如果你想了解组件发布协议(CPP),可以在下面找到更多信息。

GitHub Pages

要将 Storybook 部署到 GitHub Pages,请使用社区构建的 Deploy Storybook to GitHub Pages Action。要启用它,请在你的 .github/workflows 目录内创建一个新的工作流文件,内容如下

.github/workflows/deploy-github-pages.yml
# Workflow name
name: Build and Publish Storybook to GitHub Pages
 
on:
  # Event for the workflow to run on
  push:
    branches:
      - 'your-branch-name' # Replace with the branch you want to deploy from
 
permissions:
  contents: read
  pages: write
  id-token: write
 
# List of jobs
jobs:
  deploy:
    runs-on: ubuntu-latest
    # Job steps
    steps:
      # Manual Checkout
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      # Set up Node
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      #👇 Add Storybook build and deploy to GitHub Pages as a step in the workflow
      - uses: bitovi/github-actions-storybook-to-github-pages@v1.0.3
        with:
          install_command: yarn install # default: npm ci
          build_command: yarn build-storybook # default: npm run build-storybook
          path: storybook-static # default: dist/storybook
          checkout: false # default: true

GitHub Pages Action 需要额外的配置选项来自定义部署过程。参考官方文档了解更多信息。

组件发布协议 (CPP)

Storybook 可以与托管在线构建好的 Storybook 的服务通信。这使得组合等功能成为可能。我们根据服务对“组件发布协议”(CPP)的合规性进行分类,在 Storybook 中有不同级别的支持。

CPP level 1

此级别服务提供已发布的 Storybook 并提供以下功能

  • 版本化端点,URL 根据 version=x.y.z 查询参数(其中 x.y.z 是包的发布版本)解析到不同的已发布 Storybook。
  • 支持 /index.json(以前是 /stories.json)端点,该端点返回 stories 列表及其元数据。
  • 支持 /metadata.jsonreleases 字段。

示例:Chromatic

CPP level 0

此级别服务可以提供已发布的 Storybook,但没有与 Storybook API 的进一步集成。

示例:Netlify, S3

搜索引擎优化 (SEO)

如果你的 Storybook 是公开可见的,你可能希望配置它在搜索引擎结果页面中的显示方式。

描述

你也可以通过在 config 目录的 manager-head.html 文件中添加以下内容,为搜索引擎提供在结果列表中显示的描述

.storybook/manager-head.html
<meta name="description" content="Components for my awesome project" key="desc" />

防止你的 Storybook 被抓取

你可以通过在 config 目录的 manager-head.html 文件中包含一个 noindex meta 标签,来防止已发布的 Storybook 出现在搜索引擎结果中,你可以通过添加以下内容来实现

.storybook/manager-head.html
<meta name="robots" content="noindex" />