fragments-cloud-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fragments Cloud Setup

Fragments Cloud 配置流程

Set up design governance with Fragments Cloud -- from zero to running checks with optional CI.

在项目中通过Fragments Cloud设置设计治理——从零基础到运行检查，还可选择配置CI。

1. Detect project environment

1. 检测项目环境

Confirm the project has a
```
package.json
```
. If not, ask if the user wants to initialize one.
Detect the package manager from lock files:
- ```
bun.lockb
```
  or
```
bun.lock
```
  -> bun
- ```
pnpm-lock.yaml
```
  -> pnpm
- ```
yarn.lock
```
  -> yarn
- Otherwise -> npm
Detect the framework (React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Astro) from dependencies.
Check if
```
@fragments-sdk/ui
```
is already installed -- if so, note it and configure governance to work alongside it.

确认项目中存在
```
package.json
```
。如果不存在，询问用户是否需要初始化一个。
根据锁文件检测包管理器：
- ```
bun.lockb
```
  或
```
bun.lock
```
  -> bun
- ```
pnpm-lock.yaml
```
  -> pnpm
- ```
yarn.lock
```
  -> yarn
- 其他情况 -> npm
根据依赖项检测所使用的框架（React、Next.js、Vue、Nuxt、Svelte、SvelteKit、Astro）。
检查
```
@fragments-sdk/ui
```
是否已安装——如果已安装，记录该情况并配置治理工具以与其兼容。

2. Install the governance SDK and CLI

2. 安装治理SDK与CLI

First check if these are already available:

In a monorepo with workspace dependencies (look for
```
"workspace:*"
```
or
```
"workspace:^"
```
in
```
package.json
```
), the packages may already be linked. Check if
```
@fragments-sdk/govern
```
and
```
@fragments-sdk/cli
```
appear in
```
dependencies
```
or
```
devDependencies
```
. If they're workspace deps, skip the install step.
Also check if a
```
pnpm-workspace.yaml
```
or
```
workspaces
```
field exists in a parent directory -- if so, you're in a monorepo.

If not already installed:

bash

<package-manager> add @fragments-sdk/govern @fragments-sdk/cli

The

govern

package provides the governance engine. The

cli

package provides the

fragments

binary used to run checks.

首先检查这些工具是否已可用：

在包含工作区依赖的monorepo项目中（查看
```
package.json
```
中的
```
"workspace:*"
```
或
```
"workspace:^"
```
），相关包可能已被链接。检查
```
@fragments-sdk/govern
```
和
```
@fragments-sdk/cli
```
是否出现在
```
dependencies
```
或
```
devDependencies
```
中。如果它们是工作区依赖，跳过安装步骤。
同时检查父目录中是否存在
```
pnpm-workspace.yaml
```
或
```
workspaces
```
字段——如果存在，则当前项目为monorepo。

如果尚未安装：

bash

<package-manager> add @fragments-sdk/govern @fragments-sdk/cli

govern

包提供治理引擎，

cli

包提供用于运行检查的

fragments

可执行文件。

3. Configure the API key

3. 配置API密钥

IMPORTANT: Never ask the user to paste their API key into the chat or accept it as an argument. Never write secrets directly.

Instead, guide the user to set it themselves:

Tell the user to add their API key to
```
.env
```
(or
```
.env.local
```
) manually:
```
FRAGMENTS_API_KEY=fc_your_key_here
```
Say: "Add your Fragments Cloud API key to
```
.env
```
. You can find it in the onboarding dashboard or Settings > API Keys."
Ensure
```
.env
```
and
```
.env.local
```
are in
```
.gitignore
```
. Create
```
.gitignore
```
if needed.
Add
```
.agents/
```
to
```
.gitignore
```
if not already present (this is where installed skills live).
After the user confirms the key is set, verify it exists by checking that
```
.env
```
contains a
```
FRAGMENTS_API_KEY
```
line (do NOT read or output the actual value).

重要提示：切勿要求用户将其API密钥粘贴到聊天框中或作为参数提供。切勿直接写入机密信息。

相反，引导用户自行设置：

告知用户手动将其API密钥添加到
```
.env
```
（或
```
.env.local
```
）文件中：
```
FRAGMENTS_API_KEY=fc_your_key_here
```
说明："将你的Fragments Cloud API密钥添加到
```
.env
```
文件中。你可以在入门仪表板或设置>API密钥页面找到它。"
确保
```
.env
```
和
```
.env.local
```
已添加到
```
.gitignore
```
中。如果需要，创建
```
.gitignore
```
文件。
如果
```
.agents/
```
尚未在
```
.gitignore
```
中，将其添加进去（这是已安装技能的存储目录）。
在用户确认密钥已设置后，通过检查
```
.env
```
文件中是否包含
```
FRAGMENTS_API_KEY
```
行来验证其存在（切勿读取或输出实际密钥值）。

4. Create governance config

4. 创建治理配置文件

Create

fragments.config.ts

in the project root. Adapt the

input

glob to the detected framework:

import { defineConfig } from '@fragments-sdk/govern';

export default defineConfig({
  cloud: true,
  checks: ['accessibility', 'consistency', 'responsive'],
  input: './src/**/*.{tsx,jsx}',
});

Framework-specific

input

patterns:

Next.js App Router:

['./app/**/*.{tsx,jsx}', './components/**/*.{tsx,jsx}']

Next.js Pages:

['./pages/**/*.{tsx,jsx}', './components/**/*.{tsx,jsx}']

Vue / Nuxt:
```
['./**/*.vue']
```
Svelte / SvelteKit:
```
['./src/**/*.svelte']
```
Astro:
```
['./src/**/*.{astro,tsx,jsx}']
```

在项目根目录创建

fragments.config.ts

文件。根据检测到的框架调整

input

通配符：

import { defineConfig } from '@fragments-sdk/govern';

export default defineConfig({
  cloud: true,
  checks: ['accessibility', 'consistency', 'responsive'],
  input: './src/**/*.{tsx,jsx}',
});

各框架对应的

input

模式：

Next.js App Router:

['./app/**/*.{tsx,jsx}', './components/**/*.{tsx,jsx}']

Next.js Pages:

['./pages/**/*.{tsx,jsx}', './components/**/*.{tsx,jsx}']

Vue / Nuxt:
```
['./**/*.vue']
```
Svelte / SvelteKit:
```
['./src/**/*.svelte']
```
Astro:
```
['./src/**/*.{astro,tsx,jsx}']
```

5. Run the first check

5. 运行首次检查

bash

npx fragments govern check --cloud

Show the output. If there are violations, briefly explain what they mean and how to fix them.

bash

npx fragments govern check --cloud

展示检查结果。如果存在违规项，简要说明其含义及修复方法。

6. Offer CI/CD setup

6. 提供CI/CD配置选项

Ask: "Want to add Fragments checks to your CI pipeline? (GitHub Actions / GitLab CI / skip)"

询问："是否要将Fragments检查添加到你的CI流水线中？（GitHub Actions / GitLab CI / 跳过）"

GitHub Actions

Create

.github/workflows/fragments-check.yml

yaml

name: Fragments Design Check
on:
  pull_request:
    branches: [main, master]
permissions:
  contents: read
  pull-requests: write
jobs:
  design-check:
    name: Design Governance
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - name: Run Fragments checks
        run: npx fragments govern check --cloud --format github
        env:
          FRAGMENTS_API_KEY: ${{ secrets.FRAGMENTS_API_KEY }}

创建

.github/workflows/fragments-check.yml

文件：

yaml

name: Fragments Design Check
on:
  pull_request:
    branches: [main, master]
permissions:
  contents: read
  pull-requests: write
jobs:
  design-check:
    name: Design Governance
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - name: Run Fragments checks
        run: npx fragments govern check --cloud --format github
        env:
          FRAGMENTS_API_KEY: ${{ secrets.FRAGMENTS_API_KEY }}

GitLab CI

Add a

fragments-check

job to

.gitlab-ci.yml

yaml

fragments-check:
  stage: test
  image: node:20
  script:
    - npm ci
    - npx fragments govern check --cloud
  variables:
    FRAGMENTS_API_KEY: $FRAGMENTS_API_KEY
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

After creating the CI config, remind the user to add

FRAGMENTS_API_KEY

as a secret in their CI provider settings.

在

.gitlab-ci.yml

中添加

fragments-check

任务：

yaml

fragments-check:
  stage: test
  image: node:20
  script:
    - npm ci
    - npx fragments govern check --cloud
  variables:
    FRAGMENTS_API_KEY: $FRAGMENTS_API_KEY
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

创建CI配置后，提醒用户在其CI提供商的设置中添加

FRAGMENTS_API_KEY

作为机密信息。

7. Confirm completion

7. 确认配置完成

Summarize what was done:

```
@fragments-sdk/govern
```
and
```
@fragments-sdk/cli
```
installed
API key configured in
```
.env
```
(remind them not to commit it)
Governance config created at
```
fragments.config.ts
```
First check ran -- results visible in Fragments Cloud dashboard
CI workflow created (if chosen)

Mention related skills:

```
/fragments-govern
```
to run checks, review staged changes, and fix violations
```
/fragments-policy
```
to create custom design rules
If
```
@fragments-sdk/ui
```
is not installed, mention
```
/fragments-ui-setup
```
to add the component library

总结已完成的操作：

已安装
```
@fragments-sdk/govern
```
和
```
@fragments-sdk/cli
```
已在
```
.env
```
中配置API密钥（提醒用户不要提交该文件）
已在
```
fragments.config.ts
```
创建治理配置
已运行首次检查——结果可在Fragments Cloud仪表板查看
已创建CI工作流（如果用户选择了该选项）

提及相关技能：

```
/fragments-govern
```
：运行检查、查看暂存变更并修复违规项
```
/fragments-policy
```
：创建自定义设计规则
如果尚未安装
```
@fragments-sdk/ui
```
，提及
```
/fragments-ui-setup
```
以添加组件库