文档
Storybook 文档

发布 Storybook

观看视频教程

团队在线发布 Storybook,以审查和协作处理进行中的工作。这允许开发者、设计师、PM 和其他利益相关者检查 UI 是否外观正确,而无需接触代码或需要本地开发环境。

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

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

npm run build-storybook

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

Storybook 将创建一个静态 Web 应用程序,该应用程序可以由任何 Web 服务器提供服务。通过运行以下命令在本地预览它

npx http-server ./path/to/build

自定义构建以提高性能

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

npm run build-storybook -- --test

使用 Chromatic 发布 Storybook

一旦您将 Storybook 构建为静态 Web 应用程序,就可以将其发布到您的 Web 主机。我们推荐 Chromatic,这是一款为 Storybook 制作的免费发布服务,可在云端安全地记录、版本化和索引您的 UI 组件。

Storybook publishing workflow

首先,使用您的 GitHub、GitLab、Bitbucket 或电子邮件注册,并为您的项目生成唯一的项目令牌

接下来,从 npm 安装 Chromatic CLI

npm install chromatic --save-dev

在软件包安装完成后运行以下命令。确保将 your-project-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 的链接粘贴到 pull request 或 Slack 中。

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

UI review in Chromatic

版本控制和历史记录

当您发布 Storybook 时,您还可以获得组件历史记录和版本控制,精确到提交级别。这在实施审查期间非常有用,可以比较分支/提交之间的组件与过去的版本。

Library history in Chromatic

将 Storybook 发布到其他服务

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

GitHub Pages

要在 GitHub Pages 上部署 Storybook,请使用社区构建的 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 可以与托管在线构建的 Storybooks 的服务进行通信。这启用了诸如 组合之类的功能。我们通过符合“组件发布协议”(CPP) 将服务分类,并在 Storybook 中提供各种级别的支持。

CPP 级别 1

此级别的服务提供已发布的 Storybooks,并提供以下内容

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

示例:Chromatic

CPP 级别 0

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

示例:NetlifyS3

搜索引擎优化 (SEO)

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

描述

您可以为搜索引擎提供描述,以显示在结果列表中,方法是将以下内容添加到配置目录中的 manager-head.html 文件中

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

阻止搜索引擎抓取您的 Storybook

您可以通过包含 noindex 元标记来阻止已发布的 Storybook 出现在搜索引擎结果中,您可以通过将以下内容添加到配置目录中的 manager-head.html 文件中来实现

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