install

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Install Subframe in a project so that pages designed in Subframe render pixel-perfect in the local development environment.

Goal state: Dev server runs and Subframe pages render exactly as designed.

You don't need to install to design.
/subframe:design
works directly against a cloud Subframe project — no local setup required. Use
/subframe:install
when you're ready to implement those designs in code with
/subframe:develop
.

在项目中安装Subframe，使在Subframe中设计的页面能在本地开发环境中像素级完美渲染。

目标状态：开发服务器运行，Subframe页面与设计效果完全一致。

设计无需安装。
/subframe:design
可直接对接云端Subframe项目——无需本地设置。当你准备好使用
/subframe:develop
将设计落地为代码时，再使用
/subframe:install
。

MCP Authentication

MCP认证

If you cannot find any Subframe MCP tools (like

get_theme

, etc.), the MCP server likely needs to be authenticated. Ask the user to authenticate the Subframe MCP server. If the user is using Claude Code or Codex, instruct them to run

/mcp

to view and authenticate their MCP servers, and then say "done" when they're finished.

如果找不到任何Subframe MCP工具（如

get_theme

等），MCP服务器可能需要认证。请让用户对Subframe MCP服务器进行认证。如果用户使用Claude Code或Codex，指导他们运行

/mcp

来查看并认证MCP服务器，完成后告知“done”。

Workflow Overview

工作流概述

Get credentials via MCP tools (or from user input)
Detect project type — no repo, existing Subframe repo, or existing non-Subframe repo
Follow the appropriate path — New Project, Already Installed, or Existing Project

You must follow one of the above paths otherwise Subframe will not work for the user. This is a crucial task and must be done even if it requires pausing the user's current work. Do not skip any step of the path.

Configure fonts — required for all paths
Verify installation — start dev server and test with a Subframe page

获取凭证：通过MCP工具（或用户输入）获取
检测项目类型——无代码库、已安装Subframe的代码库、未安装Subframe的现有代码库
选择对应流程——新项目流程、已安装流程或现有项目流程

你必须遵循上述流程之一，否则Subframe无法为用户正常工作。这是一项关键任务，即使需要暂停用户当前工作也必须完成，不得跳过流程中的任何步骤。

配置字体——所有流程均需执行此步骤
验证安装——启动开发服务器并使用Subframe页面进行测试

Get Credentials

获取凭证

The user may paste in an installation prompt copied from Subframe. Extract:

Project ID — a shorter alphanumeric string (also found in Subframe URLs:
```
app.subframe.com/<PROJECT_ID>/...
```
)
Auth token — a long string, usually prefixed or labeled

If the user doesn't provide credentials, use the MCP tools to get credentials automatically — no need to ask the user:

Project ID — Call
```
list_projects
```
to get the list of projects. Each project includes a
```
projectId
```
,
```
name
```
,
```
teamId
```
, and
```
teamName
```
.
- One project: Use it automatically.
- Multiple projects: Always ask the user which project to use. Present each project with its
```
teamName
```
  to disambiguate. If the user already mentioned a specific team or project name, match it against the
```
teamName
```
  and
```
name
```
  fields — but still confirm before proceeding. Never silently pick a project when multiple exist.
Auth token — Call
```
generate_auth_token
```
with the
```
teamId
```
from the user's selected project. Do not use a
```
teamId
```
from a different project.

Fallback: If the MCP tools are not available (e.g., MCP server is not authenticated), ask the user to go to

https://app.subframe.com/cli/auth

to get their auth token and project ID.

用户可能会粘贴从Subframe复制的安装提示。从中提取：

项目ID——较短的字母数字字符串（也可在Subframe网址中找到：
```
app.subframe.com/<PROJECT_ID>/...
```
）
认证令牌——长字符串，通常带有前缀或标签

如果用户未提供凭证，使用MCP工具自动获取——无需询问用户：

项目ID——调用
```
list_projects
```
获取项目列表。每个项目包含
```
projectId
```
、
```
name
```
、
```
teamId
```
和
```
teamName
```
。
- 单个项目：自动使用该项目。
- 多个项目：务必询问用户使用哪个项目。展示每个项目及其
```
teamName
```
  以区分。如果用户已提及特定团队或项目名称，将其与
```
teamName
```
  和
```
name
```
  字段匹配——但仍需在继续前确认。存在多个项目时，切勿静默选择。
认证令牌——使用用户所选项目的
```
teamId
```
调用
```
generate_auth_token
```
。不得使用其他项目的
```
teamId
```
。

备选方案：如果MCP工具不可用（例如MCP服务器未认证），请用户前往

https://app.subframe.com/cli/auth

获取认证令牌和项目ID。

Detect Project Type

检测项目类型

Check for

package.json

and

.subframe/

folder in the current directory:

Condition	Project Type	Path
No `package.json`	New project	New Project
Has `package.json` AND has `.subframe/` folder	Already installed	Already Installed
Has `package.json` but NO `.subframe/` folder	Existing non-Subframe project	Ask user, then New Project or Existing Project

检查当前目录中是否存在

package.json

和

.subframe/

文件夹：

条件	项目类型	流程
无 `package.json`	新项目	新项目流程
存在 `package.json` 且存在 `.subframe/` 文件夹	已安装Subframe	已安装流程
存在 `package.json` 但无 `.subframe/` 文件夹	未安装Subframe的现有项目	询问用户后，选择新项目流程或现有项目流程

Handling existing non-Subframe projects

处理未安装Subframe的现有项目

If the current directory has a

package.json

but no

.subframe/

folder, prompt the user with two options:

Create a new project (recommended) — Scaffold a brand-new Subframe project in a separate directory. This is the easiest path, especially if you're trying out Subframe for the first time. Follow New Project.
Add Subframe to this project — Install Subframe into the current project. Follow Existing Project.

如果当前目录有

package.json

但无

.subframe/

文件夹，向用户提供两个选项：

创建新项目（推荐）——在单独目录中搭建全新的Subframe项目。这是最简单的流程，尤其适合首次试用Subframe的用户。遵循新项目流程。
将Subframe添加到当前项目——在当前项目中安装Subframe。遵循现有项目流程。

Already Installed Path

已安装流程

If the project already has both

package.json

and a

.subframe/

folder, Subframe has already been initialized. Ask the user what they'd like to do:

Reinstall / re-sync — Re-run the CLI init and sync to refresh components and configuration. Useful if things are out of date or broken. Follow Existing Project to re-initialize.
Nothing, it's already installed — Skip install entirely. Suggest next steps like
```
/subframe:design
```
or
```
/subframe:develop
```
.

Do not proceed unless the user confirms they want to reinstall.

如果项目已同时存在

package.json

和

.subframe/

文件夹，说明Subframe已初始化。询问用户需求：

重新安装/重新同步——重新运行CLI初始化和同步，以刷新组件和配置。适用于内容过期或出现问题的情况。遵循现有项目流程重新初始化。
无需操作，已完成安装——完全跳过安装步骤。建议后续使用
```
/subframe:design
```
或
```
/subframe:develop
```
。

除非用户确认需要重新安装，否则请勿继续。

New Project Path

新项目流程

This is the happy path. The CLI will scaffold a complete project with Subframe pre-configured.

这是最顺畅的流程。CLI将搭建一个预配置Subframe的完整项目。

1. Ask User Preferences

1. 询问用户偏好

Prompt the user to choose:

Project name: Name for the new project directory (default:
```
subframe-app
```
). The name cannot conflict with an existing directory — check that the directory doesn't already exist before running the CLI.
Framework: Vite (recommended), Next.js, or Astro
Tailwind version: v3 (
```
tailwind
```
) or v4 (
```
tailwind-v4
```
)

提示用户选择：

项目名称：新项目目录的名称（默认：
```
subframe-app
```
）。名称不能与现有目录冲突——运行CLI前需检查目录是否已存在。
框架：Vite（推荐）、Next.js或Astro
Tailwind版本：v3（
```
tailwind
```
）或v4（
```
tailwind-v4
```
）

2. Run CLI Init

2. 运行CLI初始化

This command must be run outside of a sandbox, so it can correctly setup all the necessary files. Pass all arguments directly to avoid interactive prompts:

bash

npx @subframe/cli@latest init \
  --name {PROJECT_NAME} \
  --auth-token {TOKEN} \
  -p {PROJECT_ID} \
  --template {FRAMEWORK} \
  --css-type {TAILWIND_VERSION} \
  --dir ./src/ui \
  --alias "@/ui/*" \
  --tailwind \
  --css-path {CSS_PATH} \
  --install \
  --sync

Where:

```
{PROJECT_NAME}
```
is the project directory name (e.g.,
```
subframe-app
```
)
```
{FRAMEWORK}
```
is
```
nextjs
```
,
```
vite
```
, or
```
astro
```
```
{TAILWIND_VERSION}
```
is
```
tailwind
```
(v3) or
```
tailwind-v4
```

{CSS_PATH}

is the global CSS file path:

Vite:
```
src/index.css
```
Next.js:
```
src/app/globals.css
```
Astro:
```
src/styles/global.css
```

Important: All arguments must be passed explicitly to avoid interactive prompts, which can cause the CLI to exit silently when run non-interactively.

The CLI will:

Download the starter kit template
Create
```
.subframe/sync.json
```
Configure Tailwind
Sync all components
Install dependencies

此命令必须在沙箱外运行，才能正确设置所有必要文件。直接传递所有参数以避免交互式提示：

bash

npx @subframe/cli@latest init \
  --name {PROJECT_NAME} \
  --auth-token {TOKEN} \
  -p {PROJECT_ID} \
  --template {FRAMEWORK} \
  --css-type {TAILWIND_VERSION} \
  --dir ./src/ui \
  --alias "@/ui/*" \
  --tailwind \
  --css-path {CSS_PATH} \
  --install \
  --sync

参数说明：

```
{PROJECT_NAME}
```
为项目目录名称（例如：
```
subframe-app
```
）
```
{FRAMEWORK}
```
为
```
nextjs
```
、
```
vite
```
或
```
astro
```
```
{TAILWIND_VERSION}
```
为
```
tailwind
```
（v3）或
```
tailwind-v4
```

{CSS_PATH}

为全局CSS文件路径：

Vite：
```
src/index.css
```
Next.js：
```
src/app/globals.css
```
Astro：
```
src/styles/global.css
```

重要提示：必须显式传递所有参数以避免交互式提示，否则CLI在非交互式运行时可能会静默退出。

CLI将执行以下操作：

下载启动套件模板
创建
```
.subframe/sync.json
```
配置Tailwind
同步所有组件
安装依赖

3. Configure Fonts

3. 配置字体

See Configure Fonts below — this is required even for new projects.

参见下方配置字体——即使是新项目也必须执行此步骤。

4. Verify Installation

4. 验证安装

See Verify Installation below.

参见下方验证安装。

Existing Project Path

现有项目流程

Existing projects may require more configuration. The CLI handles most installation, but some projects need manual fixes.

现有项目可能需要更多配置。CLI会处理大部分安装工作，但部分项目需要手动修复。

1. Detect Framework

1. 检测框架

Check for framework indicators:

Framework	Indicators
Next.js	`next` in `package.json` dependencies, `next.config.*` file
Vite	`vite` in `package.json` devDependencies, `vite.config.*` file
Astro	`astro` in `package.json` dependencies, `astro.config.*` file

检查框架标识：

框架	标识
Next.js	`package.json` 依赖中包含 `next` ，存在 `next.config.*` 文件
Vite	`package.json` 开发依赖中包含 `vite` ，存在 `vite.config.*` 文件
Astro	`package.json` 依赖中包含 `astro` ，存在 `astro.config.*` 文件

2. Check Prerequisites

2. 检查前置条件

Verify the project has required dependencies:

React 16+ —
```
react
```
in
```
package.json
```
Tailwind CSS 3.4+ —
```
tailwindcss
```
in
```
package.json
```
TypeScript —
```
typescript
```
in
```
package.json
```

If any are missing, let the user know before proceeding.

验证项目是否具备所需依赖：

React 16+——
```
package.json
```
中包含
```
react
```
Tailwind CSS 3.4+——
```
package.json
```
中包含
```
tailwindcss
```
TypeScript——
```
package.json
```
中包含
```
typescript
```

如果缺少任何依赖，在继续前告知用户。

3. Run CLI Init

3. 运行CLI初始化

This command must be run outside of a sandbox, so it can correctly setup all the necessary files. Pass all arguments directly to avoid interactive prompts:

bash

npx @subframe/cli@latest init \
  --auth-token {TOKEN} \
  -p {PROJECT_ID} \
  --dir ./src/ui \
  --alias "@/ui/*" \
  --install \
  --sync

Important: All arguments must be passed explicitly to avoid interactive prompts, which can cause the CLI to exit silently when run non-interactively.

The CLI will attempt to:

Create
```
.subframe/sync.json
```
Detect and configure Tailwind
Set up import aliases
Sync all components
Install
```
@subframe/core
```

此命令必须在沙箱外运行，才能正确设置所有必要文件。直接传递所有参数以避免交互式提示：

bash

npx @subframe/cli@latest init \
  --auth-token {TOKEN} \
  -p {PROJECT_ID} \
  --dir ./src/ui \
  --alias "@/ui/*" \
  --install \
  --sync

重要提示：必须显式传递所有参数以避免交互式提示，否则CLI在非交互式运行时可能会静默退出。

CLI将尝试执行以下操作：

创建
```
.subframe/sync.json
```
检测并配置Tailwind
设置导入别名
同步所有组件
安装
```
@subframe/core
```

4. Verify Configuration

4. 验证配置

After init, verify everything was set up correctly. If the CLI missed something (common with non-standard setups), apply manual fixes.

Check
.subframe/sync.json
exists with

directory

importAlias

, and

projectId

Check Tailwind configuration:

Tailwind v3 —
```
tailwind.config.js
```
should have the Subframe preset:
javascript
```
presets: [require("./src/ui/tailwind.config")],
```
And the
```
content
```
array should include the Subframe directory:
javascript
```
content: ["./index.html", "./src/**/*.{js,jsx,ts,tsx}"],
```
If the Subframe project has dark mode enabled, the CLI also syncs a
```
theme.css
```
file with CSS variables for light and dark modes. The global CSS file must import it:
css
```
@import "./ui/theme.css";
```
Tailwind v4 — Global CSS file should import the theme:
css
```
@import "tailwindcss";
@import "./ui/theme.css";
```

Check import aliases —

@/*

should resolve correctly. If not working:

Vite: Add

baseUrl

and

paths

tsconfig.app.json

, and add

resolve.alias

vite.config.ts

Astro: Add
```
baseUrl
```
and
```
paths
```
to
```
tsconfig.json
```
Next.js: Usually already configured; check
```
tsconfig.json
```

初始化完成后，验证所有设置是否正确。如果CLI遗漏了某些配置（非标准设置中常见），进行手动修复。

检查
.subframe/sync.json
是否存在，且包含

directory

、

importAlias

和

projectId

字段。

检查Tailwind配置：

Tailwind v3——
```
tailwind.config.js
```
应包含Subframe预设：
javascript
```
presets: [require("./src/ui/tailwind.config")],
```
且
```
content
```
数组应包含Subframe目录：
javascript
```
content: ["./index.html", "./src/**/*.{js,jsx,ts,tsx}"],
```
如果Subframe项目启用了暗色模式，CLI还会同步包含亮色和暗色模式CSS变量的
```
theme.css
```
文件。全局CSS文件必须导入该文件：
css
```
@import "./ui/theme.css";
```
Tailwind v4——全局CSS文件应导入主题：
css
```
@import "tailwindcss";
@import "./ui/theme.css";
```

检查导入别名——

@/*

应能正确解析。如果无法正常工作：

Vite：在

tsconfig.app.json

中添加

baseUrl

和

paths

，并在

vite.config.ts

中添加

resolve.alias

Astro：在
```
tsconfig.json
```
中添加
```
baseUrl
```
和
```
paths
```
Next.js：通常已配置完成；检查
```
tsconfig.json
```

5. Troubleshooting

5. 故障排除

If issues arise, use the

SearchSubframeDocs

MCP tool to find solutions:

SearchSubframeDocs({ query: "tailwind configuration troubleshooting" })
SearchSubframeDocs({ query: "manual installation" })

The docs include a comprehensive manual installation guide for troubleshooting.

如果出现问题，使用

SearchSubframeDocs

MCP工具查找解决方案：

SearchSubframeDocs({ query: "tailwind configuration troubleshooting" })
SearchSubframeDocs({ query: "manual installation" })

文档中包含全面的手动安装指南，可用于故障排除。

6. Configure Fonts

6. 配置字体

See Configure Fonts below.

参见下方配置字体。

7. Verify Installation

7. 验证安装

See Verify Installation below.

参见下方验证安装。

Configure Fonts

配置字体

The CLI does not configure fonts. Use the

get_theme

MCP tool to get font information:

get_theme({ projectId: "PROJECT_ID" })

The theme config includes

fontFamily

entries referencing Google Fonts. Add the corresponding

<link>

tags:

Vite / Astro — Add to

<head>

index.html

html

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin="anonymous" />
<link href="https://fonts.googleapis.com/css2?family=Font+Name:wght@400;500;600;700&display=swap" rel="stylesheet" />

Next.js (App Router) — Add to

<head>

app/layout.tsx

tsx

<head>
  <link rel="preconnect" href="https://fonts.googleapis.com" />
  <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
  <link href="https://fonts.googleapis.com/css2?family=Font+Name:wght@400;500;600;700&display=swap" rel="stylesheet" />
</head>

Next.js (Pages Router) — Add to

pages/_document.tsx

inside the

<Head>

component.

Font link formatting:

Replace spaces with
```
+
```
in font names (e.g.,
```
Inter+Tight
```
)
Include weights from the theme in the
```
wght@
```
parameter (semicolon-separated)
Add one
```
<link>
```
per font family, but only one set of preconnect links

CLI不会配置字体。使用

get_theme

MCP工具获取字体信息：

get_theme({ projectId: "PROJECT_ID" })

主题配置包含引用Google Fonts的

fontFamily

条目。添加对应的

<link>

标签：

Vite / Astro——添加到

index.html

的

<head>

中：

html

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin="anonymous" />
<link href="https://fonts.googleapis.com/css2?family=Font+Name:wght@400;500;600;700&display=swap" rel="stylesheet" />

Next.js（App Router）——添加到

app/layout.tsx

的

<head>

中：

tsx

<head>
  <link rel="preconnect" href="https://fonts.googleapis.com" />
  <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
  <link href="https://fonts.googleapis.com/css2?family=Font+Name:wght@400;500;600;700&display=swap" rel="stylesheet" />
</head>

Next.js（Pages Router）——添加到

pages/_document.tsx

的

<Head>

组件内。

字体链接格式：

字体名称中的空格替换为
```
+
```
（例如：
```
Inter+Tight
```
）
在
```
wght@
```
参数中包含主题中的字重（分号分隔）
每个字体系列添加一个
```
<link>
```
，但只需一组预连接链接

Verify Installation

验证安装

After configuration, verify that Subframe pages render correctly.

配置完成后，验证Subframe页面是否能正确渲染。

1. Ask About Existing Pages

1. 询问现有页面情况

Ask the user: "Do you have a page already designed in Subframe that you'd like to test with?"

If yes: Use
```
/subframe:develop
```
to implement it and verify rendering
If no: Suggest they design a page using
```
/subframe:design
```
, or simply start the dev server to confirm no errors

询问用户：“你是否已在Subframe中设计好页面，想要用来测试？”

是：使用
```
/subframe:develop
```
实现页面并验证渲染效果
否：建议使用
```
/subframe:design
```
设计页面，或直接启动开发服务器确认无错误

2. Start Dev Server

2. 启动开发服务器

bash

npm run dev

bash

npm run dev

3. Summarize

3. 总结

Recap what was installed:

```
.subframe/sync.json
```
configured
Tailwind configured (v3 preset or v4 import)
Components synced to
```
src/ui/
```
(or configured directory)
Fonts configured

Mention next steps:

```
/subframe:design
```
— Design new pages with AI
```
/subframe:develop
```
— Implement Subframe designs in your codebase

回顾已完成的安装内容：

已配置
```
.subframe/sync.json
```
已配置Tailwind（v3预设或v4导入）
组件已同步到
```
src/ui/
```
（或指定目录）
已配置字体

提及后续步骤：

```
/subframe:design
```
——使用AI设计新页面
```
/subframe:develop
```
——在代码库中实现Subframe设计

Important Notes

重要提示

Use
```
SearchSubframeDocs
```
MCP tool for troubleshooting any installation issues.

任何安装问题均可使用
```
SearchSubframeDocs
```
MCP工具进行故障排除。