create-app

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When To Use

何时使用

Pick this skill when the user wants to start a brand-new Twenty app from scratch. Representative triggers:

"I want to build a Twenty app"
"scaffold a new Twenty app"
"start a new Twenty plugin / extension / integration"
"create a CRM extension for Twenty"
"set up a Twenty app project"
"bootstrap a Twenty app called X"

Do not use this skill when the app already exists — use

develop-app

to add features,

manage-app

for sync/deploy/troubleshooting,

publish-app

for marketplace prep, or

use-twenty-mcp

to query workspace data.

当用户想从头开始创建一个全新的 Twenty 应用时，选择此 skill。典型触发场景包括：

“我想构建一个 Twenty 应用”
“搭建一个新的 Twenty 应用”
“启动一个新的 Twenty 插件／扩展／集成”
“为 Twenty 创建一个 CRM 扩展”
“设置一个 Twenty 应用项目”
“初始化一个名为 X 的 Twenty 应用”

如果应用已经存在，则不要使用此 skill——应使用

develop-app

添加功能，使用

manage-app

进行同步、部署或故障排查，使用

publish-app

准备应用市场发布，或使用

use-twenty-mcp

查询工作区数据。

Quickstart an App

快速启动应用

For background on how Twenty apps work — the SDK packages, remotes, sync lifecycle, and rendering model — read

../../references/concepts/how-apps-work.md

. Cross-skill operating rules that apply to every Twenty app task are in

../../references/concepts/operating-rules.md

; they are authoritative and not restated per skill.

Use this as the default way to start an app unless the user gives different instructions.

如需了解 Twenty 应用的运作方式——包括 SDK 包、remote、同步生命周期和渲染模型——请阅读

../../references/concepts/how-apps-work.md

。适用于所有 Twenty 应用任务的跨 skill 操作规则位于

../../references/concepts/operating-rules.md

；这些规则具有权威性，无需在每个 skill 中重复说明。

除非用户给出其他指示，否则默认使用以下方式启动应用。

Why A Twenty Instance Is Needed

为什么需要 Twenty 实例

Before scaffolding, explain to the user that a Twenty app is not a standalone application — it is a package that extends a running Twenty instance. During development, the app's entities (objects, views, front components, logic functions) are synced to a Twenty instance where they are registered, rendered, and executed. Without a connected instance, there is nothing to sync to, no workspace to test in, and no way to verify the app works.

在搭建应用之前，应向用户说明，Twenty 应用并非独立应用，而是用于扩展正在运行的 Twenty 实例的包。在开发过程中，应用的实体（对象、视图、前端组件、逻辑函数）会同步到 Twenty 实例，并在其中完成注册、渲染和执行。如果没有连接的实例，就没有可供同步的目标、没有可用于测试的工作区，也无法验证应用是否正常工作。

Choose A Twenty Instance

选择 Twenty 实例

By default, ask the user for the URL of their existing Twenty instance (e.g.

https://app.twenty.com

or a self-hosted URL). Mention that if they don't have one yet, you can spin up a local instance with Docker instead.

The two options are:

Existing Twenty instance (default) — the user provides the URL of a running Twenty server (self-hosted or cloud, e.g.
```
https://app.twenty.com
```
). The scaffolder authenticates via OAuth on that instance. Best when the user already has a workspace with data they want to develop against.
Local instance with Docker (fallback) — only when the user has no Twenty instance available. The scaffolder starts a disposable local Twenty server on
```
http://localhost:2020
```
through Docker. Requires Docker Desktop to be installed and running.

If the user does not provide a URL, ask first whether they have a Twenty instance URL to use; only fall back to Docker if they explicitly say they don't have one.

Before scaffolding, repeat back the app's purpose in one sentence and its expected shape: standard objects extended, any custom objects, whether it needs UI, whether it needs workflows or post-install seeding. Scaffolding is one-way — confirming here avoids re-scaffolds later.

默认情况下，应询问用户其现有 Twenty 实例的 URL（例如

https://app.twenty.com

或自托管 URL）。同时说明：如果用户还没有实例，可以使用 Docker 启动本地实例。

有两种选择：

现有 Twenty 实例（默认）——用户提供正在运行的 Twenty 服务器 URL（自托管或云端，例如
```
https://app.twenty.com
```
）。脚手架工具会通过 OAuth 在该实例上进行身份验证。当用户已有包含所需数据的工作区并希望基于其进行开发时，此选项最为合适。
使用 Docker 的本地实例（备用）——仅当用户没有可用的 Twenty 实例时使用。脚手架工具会通过 Docker 在
```
http://localhost:2020
```
启动一个临时的本地 Twenty 服务器。要求已安装并运行 Docker Desktop。

如果用户未提供 URL，应先询问是否有可用的 Twenty 实例 URL；只有用户明确表示没有实例时，才回退到 Docker。

在搭建应用之前，应先用一句话复述应用的用途及其预期形态：扩展哪些标准对象、是否包含自定义对象、是否需要 UI、是否需要工作流或安装后数据初始化。搭建过程不可逆，因此在此处确认可以避免后续重复搭建。

Scaffolding

搭建应用

First, ask the user for the app name if they did not provide one.

The directory name must contain only lowercase letters, numbers, and hyphens. Transform the entered name to lowercase and replace spaces with hyphens when needed.

For an existing Twenty instance (default):

bash

npx create-twenty-app@latest <app-name> --url <twenty-instance-url>

The

--url

flag authenticates via OAuth on the provided instance. The scaffolder opens a browser for the OAuth flow, then stores the credentials as a remote in

~/.twenty/config.json

Only if the user has no Twenty instance and wants to try locally with Docker:

bash

npx create-twenty-app@latest <app-name>

This omits

--url

and starts a disposable local Twenty server through Docker.

The scaffolder handles everything: it creates the project, enables corepack, installs dependencies, initializes Git, authenticates with the target instance, runs an initial sync, and opens the generated app page when possible.

If the user provides a package name, display name, or description, pass them through:

bash

npx create-twenty-app@latest <app-directory> --name "<package-name>" --display-name "<display-name>" --description "<description>"

Supported create-time options are

--name

--display-name

--description

--url

, and

--authentication-method

如果用户尚未提供应用名称，应先询问应用名称。

目录名只能包含小写字母、数字和连字符。必要时，应将输入的名称转换为小写，并用连字符替换空格。

对于现有 Twenty 实例（默认）：

bash

npx create-twenty-app@latest <app-name> --url <twenty-instance-url>

--url

参数用于通过 OAuth 在所提供的实例上进行身份验证。脚手架工具会打开浏览器完成 OAuth 流程，然后将凭据作为 remote 存储在

~/.twenty/config.json

中。

仅当用户没有 Twenty 实例且希望使用 Docker 在本地尝试时：

bash

npx create-twenty-app@latest <app-name>

此命令不包含

--url

，会通过 Docker 启动一个临时的本地 Twenty 服务器。

脚手架工具会处理所有事项：创建项目、启用 corepack、安装依赖、初始化 Git、针对目标实例进行身份验证、执行首次同步，并在可行时打开生成的应用页面。

如果用户提供包名、显示名称或描述，应将其传入：

bash

npx create-twenty-app@latest <app-directory> --name "<package-name>" --display-name "<display-name>" --description "<description>"

创建时支持的选项包括

--name

、

--display-name

、

--description

、

--url

和

--authentication-method

。

After Scaffolding

搭建完成后

When the scaffolder completes, the app is fully created, synced, and installed. The job is done.

Do not run any follow-up validation commands after scaffolding unless the user asks for them. Do not run

yarn twenty apply

yarn test

yarn lint

, or other validation just to prove the scaffold worked; the scaffolder already performed the initial sync. If the user asks to run tests later, switch to

develop-app

manage-app

guidance and run the full suite against the isolated test instance with

TWENTY_API_URL=http://localhost:2021

Report to the user that the app was created successfully and is ready for development. Then stop. Wait for the user to ask for the next action.

The scaffolder generates a placeholder page at

src/front-components/main-page.tsx

plus its page layout and navigation menu item. In

develop-app

, delete all three before the first deploy unless the app actually needs UI. Do not stack additional pages on top of the placeholder.

It also generates a health check at

src/logic-functions/health-check.ts

that reports

OK

. Customise that file when the app gains something worth reporting; do not add a second one, since an app may declare only one health check and a second fails the build.

脚手架工具执行完成后，应用即已完整创建、同步并安装，任务已经完成。

除非用户要求，否则搭建完成后不要运行任何后续验证命令。不要仅为证明脚手架运行成功而执行

yarn twenty apply

、

yarn test

、

yarn lint

或其他验证命令；脚手架工具已经完成首次同步。如果用户之后要求运行测试，请切换到

develop-app

或

manage-app

指南，并使用

TWENTY_API_URL=http://localhost:2021

针对隔离的测试实例运行完整测试套件。

告知用户应用已成功创建并可进入开发阶段，然后停止操作，等待用户提出下一步要求。

脚手架工具会在

src/front-components/main-page.tsx

生成一个占位页面，同时生成其页面布局和导航菜单项。在

develop-app

中，除非应用确实需要 UI，否则应在首次部署前删除这三项。不要在占位页面上叠加其他页面。

它还会在

src/logic-functions/health-check.ts

中生成一个返回

OK

的健康检查。当应用出现值得报告的内容后，可自定义此文件；不要添加第二个健康检查，因为一个应用只能声明一个健康检查，添加第二个会导致构建失败。

Docker Fallback Troubleshooting

Docker 备用方案故障排查

Use this only when the user opted into the Docker fallback and it fails because Docker is missing or not running.

The preferred recovery is to ask the user for an existing Twenty instance URL and rerun the scaffolder with

--url <twenty-instance-url>

— this skips Docker entirely.

If the user still wants the local Docker path and Docker is missing, share this download link:

https://www.docker.com/products/docker-desktop/

and ask them to install Docker Desktop.

仅当用户选择 Docker 备用方案，并且由于 Docker 未安装或未运行而失败时，才使用以下说明。

首选恢复方式是让用户提供现有 Twenty 实例的 URL，并使用

--url <twenty-instance-url>

重新运行脚手架工具——这样可以完全跳过 Docker。

如果用户仍希望使用本地 Docker 方案，但尚未安装 Docker，请提供下载链接

https://www.docker.com/products/docker-desktop/

，并请用户安装 Docker Desktop。

Next Steps

后续步骤

Only proceed to these when the user explicitly asks:

Use
```
develop-app
```
when the user wants to add objects, fields, logic functions, roles, views, navigation, page layouts, skills, agents, front component registrations, or settings menu items.
Use
```
../../references/design/front-component-ui.md
```
when the user wants to design or improve the UI of a Twenty front component.
When the user later makes changes to app entities, use
```
yarn twenty apply
```
to sync those changes. See the
```
manage-app
```
skill for sync workflow.

仅在用户明确要求时执行以下操作：

当用户希望添加对象、字段、逻辑函数、角色、视图、导航、页面布局、skill、Agent、前端组件注册项或设置菜单项时，使用
```
develop-app
```
。
当用户希望设计或改进 Twenty 前端组件的 UI 时，参考
```
../../references/design/front-component-ui.md
```
。
当用户之后修改应用实体时，使用
```
yarn twenty apply
```
同步这些更改。有关同步工作流，请参阅
```
manage-app
```
skill。