发布 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 组件。
开始使用,请使用你的 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.
设置 CI 自动发布
配置你的 CI 环境,以便在你将代码推送到仓库时发布你的 Storybook 并 运行 Chromatic。让我们看看如何使用 GitHub Actions 进行设置。
在你的项目根目录中,在 .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 链接。
与你的团队一起评审
将 Storybook 作为开发过程的一部分发布,可以快速轻松地收集团队反馈。
一个常见的征求评审的方法是将已发布的 Storybook 链接粘贴到拉取请求或 Slack 中。
如果你将 Storybook 发布到 Chromatic,你可以使用 UI Review 功能自动扫描你的 PR 以查找新的和更新的 stories。这使得识别更改并提供反馈变得容易。
版本控制和历史记录
发布 Storybook 时,你还可以获得组件历史记录和版本控制,精确到每次提交。这在实施评审期间比较不同分支/提交与过去版本的组件时非常有用。
将 Storybook 发布到其他服务
由于 Storybook 被构建为静态 Web 应用程序,你也可以将其发布到任何 Web 主机,包括 GitHub Pages、Netlify、AWS S3 等。但是,组合、嵌入 stories、历史记录、版本控制和资产等功能可能需要与 Storybook API 进行更紧密的集成以及安全认证。如果你想了解更多关于头的信息,可以参考迁移指南。此外,如果你想了解组件发布协议(CPP),可以在下面找到更多信息。
GitHub Pages
要将 Storybook 部署到 GitHub Pages,请使用社区构建的 Deploy Storybook to GitHub Pages Action。要启用它,请在你的 .github/workflows
目录内创建一个新的工作流文件,内容如下
# 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.json
和releases
字段。
示例:Chromatic
CPP level 0
此级别服务可以提供已发布的 Storybook,但没有与 Storybook API 的进一步集成。
搜索引擎优化 (SEO)
如果你的 Storybook 是公开可见的,你可能希望配置它在搜索引擎结果页面中的显示方式。
描述
你也可以通过在 config 目录的 manager-head.html
文件中添加以下内容,为搜索引擎提供在结果列表中显示的描述
<meta name="description" content="Components for my awesome project" key="desc" />
防止你的 Storybook 被抓取
你可以通过在 config 目录的 manager-head.html
文件中包含一个 noindex meta 标签,来防止已发布的 Storybook 出现在搜索引擎结果中,你可以通过添加以下内容来实现
<meta name="robots" content="noindex" />