bklit-ship

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bklit Ship Skill

Bklit Ship Skill（组件发布操作指南）

This skill is for bklit-ui monorepo contributors taking an experimental chart or component from prototype (usually on an untracked route like the playground) into production: published in the UI package, documented, and ready for users.

本操作指南专为bklit-ui 单体仓库贡献者设计，帮助你将实验性的图表或组件从原型阶段（通常位于Playground这类未追踪路由中）推进到生产环境：发布到UI包中、完成文档编写，并准备好供用户使用。

When to use this skill

使用场景

You cloned
```
bklit/bklit-ui
```
and have a working prototype on a temporary route (e.g.
```
apps/web/app/playground/page.tsx
```
) and want to ship it.
You are ready to move from "scaffolding" to "permanent": the API and key props/variants are decided from the prototyping phase.

你克隆了
```
bklit/bklit-ui
```
仓库，且在临时路由（如
```
apps/web/app/playground/page.tsx
```
）上有一个可运行的原型，想要将其正式发布。
你已准备好从“搭建原型”阶段过渡到“正式上线”：原型阶段确定的API和关键属性/变体已最终敲定。

Plan: Prototype → Production

流程：原型 → 生产环境

Follow these steps in order. Treat this as a checklist; each step has concrete locations in the repo.

请按以下顺序执行步骤，将此视为检查清单；每个步骤都对应仓库中的具体位置。

1. Move into the UI package and export

1. 迁移至UI包并导出

Move the chart/component source files from the app (e.g. playground) into
```
packages/ui/
```
in the right place (e.g.
```
packages/ui/src/charts/
```
for charts).
Export the new chart/component from the package’s public API:
- For charts: add exports in
```
packages/ui/src/charts/index.ts
```
  .
- If the package uses
```
exports
```
  in
```
package.json
```
  for specific entry points, add or update the relevant entry so the new component is importable as
```
@bklitui/ui/charts
```
  (or the appropriate path).
Remove or trim the prototype code from the temporary route (e.g.
```
apps/web/app/playground/page.tsx
```
) so the app no longer depends on in-app-only copies of the component.

迁移：将图表/组件的源文件从应用（如Playground）移动到
```
packages/ui/
```
中的对应目录（例如图表放在
```
packages/ui/src/charts/
```
）。
导出：在包的公开API中导出新的图表/组件：
- 对于图表：在
```
packages/ui/src/charts/index.ts
```
  中添加导出语句。
- 如果包在
```
package.json
```
  中使用
```
exports
```
  定义特定入口点，请添加或更新相关入口，使新组件可通过
```
@bklitui/ui/charts
```
  （或对应路径）导入。
清理：从临时路由（如
```
apps/web/app/playground/page.tsx
```
）中移除或精简原型代码，确保应用不再依赖仅在内部使用的组件副本。

2. Documentation and examples (apps/web)

2. 文档与示例（apps/web）

Documentation lives under

apps/web/

. Do all of the following.

Chart examples (live demos)
- In
```
apps/web/components/charts/chart-slugs.ts
```
  : add the new chart’s slug to the
```
validChartSlugs
```
  array (e.g.
```
"my-chart"
```
  ).
- In
```
apps/web/components/charts/chart-examples.tsx
```
  :
  - Add a nav entry in the
```
CHART_NAV_ITEMS
```
    array (or equivalent list used for the chart-type tabs).
  - Register the chart in the chart examples registry: add a
```
factory
```
    (and optionally
```
hero
```
    ) for the new slug so the chart appears on
```
/charts/[chart]
```
    with the same pattern as existing charts (e.g. area-chart, line-chart). Reuse or mirror the prop variants you validated in the scaffolding phase.
Docs page for the component
- Add a new MDX file under
```
apps/web/content/docs/components/
```
  , e.g.
```
my-chart.mdx
```
  , with:
  - Frontmatter:
```
title
```
    ,
```
description
```
    .
  - Preview (e.g.
```
<ComponentPreview>
```
    ), installation (e.g.
```
<InstallationTabs>
```
    ), and usage sections consistent with other component docs (see e.g.
```
line-chart.mdx
```
    ).
Components index
- The Components page at
```
apps/web/content/docs/components/index.mdx
```
  uses
```
<ComponentsList />
```
  , which lists all pages under
```
content/docs/components/
```
  . Adding the new
```
.mdx
```
  file is enough for it to appear if the sidebar includes it (see next).
Sidebar (desktop and mobile)
- Desktop: The docs sidebar is built from the Fumadocs source (file-based). Add the new doc to the components section by adding its slug to
```
apps/web/content/docs/components/meta.json
```
  in the
```
pages
```
  array (e.g.
```
"my-chart"
```
  ), so the new page appears in the Components folder in the sidebar.
- Mobile: The mobile nav has a hardcoded
```
components
```
  list in
```
apps/web/components/docs/site-header.tsx
```
  . Add an entry there for the new chart (e.g.
```
{ text: "My Chart", url: "/docs/components/my-chart" }
```
  ) so it appears in the mobile menu under Components.

文档存储在

apps/web/

目录下，请完成以下所有操作。

图表示例（实时演示）
- 在
```
apps/web/components/charts/chart-slugs.ts
```
  中：将新图表的slug添加到
```
validChartSlugs
```
  数组中（例如
```
"my-chart"
```
  ）。
- 在
```
apps/web/components/charts/chart-examples.tsx
```
  中：
  - 在
```
CHART_NAV_ITEMS
```
    数组（或用于图表类型标签页的等效列表）中添加导航条目。
  - 在图表示例注册表中注册该图表：为新slug添加
```
factory
```
    （可选添加
```
hero
```
    ），使图表按照现有图表（如面积图、折线图）的相同模式显示在
```
/charts/[chart]
```
    页面上。复用或镜像你在原型阶段验证过的属性变体。
组件文档页
- 在
```
apps/web/content/docs/components/
```
  下添加新的MDX文件，例如
```
my-chart.mdx
```
  ，包含：
  - 前置元数据：
```
title
```
    、
```
description
```
    。
  - 预览（如
```
<ComponentPreview>
```
    ）、安装（如
```
<InstallationTabs>
```
    ）和使用章节，格式与其他组件文档保持一致（可参考
```
line-chart.mdx
```
    ）。
组件索引页
- ```
apps/web/content/docs/components/index.mdx
```
  中的组件页面使用
```
<ComponentsList />
```
  ，该组件会列出
```
content/docs/components/
```
  下的所有页面。只要侧边栏包含该页面，添加新的
```
.mdx
```
  文件后，它就会自动显示在索引中（见下一步）。
侧边栏（桌面端与移动端）
- 桌面端：文档侧边栏基于Fumadocs的文件结构生成。将新文档的slug添加到
```
apps/web/content/docs/components/meta.json
```
  的
```
pages
```
  数组中（例如
```
"my-chart"
```
  ），使新页面出现在侧边栏的“组件”文件夹下。
- 移动端：移动端导航在
```
apps/web/components/docs/site-header.tsx
```
  中有一个硬编码的
```
components
```
  列表。为新图表添加一个条目（例如
```
{ text: "My Chart", url: "/docs/components/my-chart" }
```
  ），使其出现在移动端菜单的“组件”分类下。

3. Rebuild the shadcn registry

3. 重建shadcn注册表

From the repo root: run
```
pnpm registry:build
```
(or the equivalent that runs the UI package’s
```
registry:build
```
script).
This updates
```
apps/web/public/r/
```
from
```
packages/ui
```
(including
```
registry.json
```
and per-component JSON). If the new chart is a shadcn-registry component, ensure it’s listed in
```
packages/ui/registry.json
```
(or the structure your registry uses) so the build outputs the new component’s registry files.

在仓库根目录下：运行
```
pnpm registry:build
```
（或执行UI包中
```
registry:build
```
脚本的等效命令）。
此命令会从
```
packages/ui
```
更新
```
apps/web/public/r/
```
目录（包括
```
registry.json
```
和各组件的JSON文件）。如果新图表是shadcn注册表组件，请确保它已列在
```
packages/ui/registry.json
```
中（或你的注册表使用的对应结构），以便构建过程输出新组件的注册表文件。

4. Lint, format, and hooks

4. 代码检查、格式化与钩子验证

Run ultracite (lint): e.g.
```
pnpm lint
```
; fix issues with
```
pnpm lint:fix
```
or the project’s lint:fix script.
Run format: e.g.
```
pnpm format
```
(or the script that runs the formatter).
Run prepare (husky): ensure pre-commit hooks run (e.g.
```
pnpm prepare
```
if needed, and then commit so hooks execute).
Fix any reported warnings or errors and repeat until the tree is clean (no lint/format/type errors and no hook failures).

运行ultracite（代码检查）：例如
```
pnpm lint
```
；使用
```
pnpm lint:fix
```
或项目的lint:fix脚本修复问题。
运行格式化：例如
```
pnpm format
```
（或执行格式化工具的脚本）。
运行prepare（husky钩子）：确保预提交钩子正常运行（如有需要可执行
```
pnpm prepare
```
，然后提交代码触发钩子执行）。
修复所有报告的警告或错误，并重复执行直到代码无任何检查/格式化/类型错误，且钩子验证通过。

5. Commit, push, and open a PR

5. 提交、推送并创建PR

Commit with a short, clear message (e.g.
```
feat(charts): add MyChart component
```
).
Push the branch (e.g.
```
git push --set-upstream origin <branch>
```
if first push).
Open a PR (do not only update a template file—actually create the pull request):
- After pushing, run gh pr create
  (GitHub CLI) with a title and body, or open the “Compare & pull request” link from the repo’s PR/new view. Use a template body if one exists (e.g.
```
.github/PULL_REQUEST_TEMPLATE_*.md
```
  ).
- The PR must include:
  - Chart/component moved to
```
packages/ui
```
    and exported
  - Chart slug and examples added (
```
chart-slugs.ts
```
    ,
```
chart-examples.tsx
```
    )
  - New doc page under
```
content/docs/components/*.mdx
```
  - Component added to
```
content/docs/components/meta.json
```
    (sidebar)
  - Component added to
```
site-header.tsx
```
    components list (mobile nav)
  - Registry rebuilt (
```
pnpm registry:build
```
    )
  - Lint/format and hooks pass with no errors or warnings

提交：使用简短清晰的提交信息（例如
```
feat(charts): add MyChart component
```
）。
推送：推送分支（如果是首次推送，可执行
```
git push --set-upstream origin <branch>
```
）。
创建PR（不要仅更新模板文件——需实际创建拉取请求）：
- 推送后，运行**
```
gh pr create
```
  **（GitHub CLI）并填写标题和正文，或从仓库的PR/new页面打开“Compare & pull request”链接。如果存在模板（如
```
.github/PULL_REQUEST_TEMPLATE_*.md
```
  ），请使用模板正文。
- PR必须包含以下内容：
  - 图表/组件已迁移至
```
packages/ui
```
    并完成导出
  - 已添加图表slug和示例（
```
chart-slugs.ts
```
    、
```
chart-examples.tsx
```
    ）
  - 在
```
content/docs/components/*.mdx
```
    下添加了新的文档页
  - 已将组件添加到
```
content/docs/components/meta.json
```
    （侧边栏）
  - 已将组件添加到
```
site-header.tsx
```
    的components列表（移动端导航）
  - 已重建注册表（
```
pnpm registry:build
```
    ）
  - 代码检查/格式化与钩子验证无错误或警告

File reference (quick lookup)

文件参考（快速查找）

Step	Location
Chart exports	`packages/ui/src/charts/index.ts`
Chart slugs	`apps/web/components/charts/chart-slugs.ts`
Chart examples (nav + registry)	`apps/web/components/charts/chart-examples.tsx`
Component docs	`apps/web/content/docs/components/<name>.mdx`
Components index	`apps/web/content/docs/components/index.mdx` (list is auto from docs pages)
Sidebar (desktop)	`apps/web/content/docs/components/meta.json` → `pages`
Mobile nav	`apps/web/components/docs/site-header.tsx` → `components` array
Registry (source)	`packages/ui/registry.json` ; build output: `apps/web/public/r/`
Registry build	From root: `pnpm registry:build`

步骤	位置
图表导出	`packages/ui/src/charts/index.ts`
图表Slug	`apps/web/components/charts/chart-slugs.ts`
图表示例（导航+注册表）	`apps/web/components/charts/chart-examples.tsx`
组件文档	`apps/web/content/docs/components/<name>.mdx`
组件索引页	`apps/web/content/docs/components/index.mdx` （列表自动从文档页生成）
桌面端侧边栏	`apps/web/content/docs/components/meta.json` → `pages`
移动端导航	`apps/web/components/docs/site-header.tsx` → `components` 数组
注册表（源文件）	`packages/ui/registry.json` ；构建输出： `apps/web/public/r/`
注册表构建	根目录执行： `pnpm registry:build`