使用 create-twenty-app 脚手架创建 Twenty 应用：从项目生成、OAuth 认证到首次同步的完整指南

使用 create-twenty-app 脚手架创建 Twenty 应用从项目生成、OAuth 认证到首次同步的完整指南【免费下载链接】twentyThe open alternative to Salesforce, designed for AI.项目地址: https://gitcode.com/GitHub_Trending/tw/twenty导读Twenty 应用不是独立运行的服务而是一个寄生于运行中 Twenty 实例的扩展包它的对象objects、视图views、前端组件front components、逻辑函数logic functions等实体都需要同步到一个真实的 Twenty 实例中才能被注册、渲染和执行。本指南以 packages/twenty-codex-plugin/skills/create-app/SKILL.md 为核心结合create-twenty-app脚手架的源码实现系统讲解如何从零开始生成一个 Twenty 应用项目。读完你将掌握脚手架工具的全部命令参数、两种连接实例的方式远程 OAuth 与本地 Docker、脚手架内部执行步骤与产物结构以及创建完成后的正确后续动作与故障排查方法。何时使用 create-app Skillcreate-app是 Twenty Codex 插件packages/twenty-codex-plugin中的核心 Skill 之一。当用户想要从零开始新建一个 Twenty 应用时应启用该 Skill。SKILL.md 中给出了如下典型触发语句I want to build a Twenty appscaffold a new Twenty appstart a new Twenty plugin / extension / integrationcreate a CRM extension for Twentyset up a Twenty app projectbootstrap a Twenty app called X值得注意的是create-app只负责从无到有的项目生成。Skill 文档明确划定了边界如果应用已经存在则不应使用本 Skill而应切换到其他 Skill —— 使用 develop-app SKILL 添加功能使用 manage-app SKILL 处理同步、部署与排障使用 publish-app SKILL 做发布前的准备使用use-twenty-mcp查询工作区数据。这一分工意味着脚手架是一次性操作且方向不可逆——因此 SKILL 建议在动手前把应用目的、要扩展的标准对象、是否需要自定义对象、是否需要 UI、是否需要工作流或安装后数据填充等内容与用户确认清楚避免之后反复重建。前置概念为什么必须有一个运行中的 Twenty 实例在开始脚手架之前需要先向用户解释一个核心事实Twenty 应用不是独立应用而是扩展某个运行中 Twenty 实例的包。在开发期间应用的实体对象、视图、前端组件、逻辑函数会被同步到某个 Twenty 实例在那里完成注册、渲染和执行。如果没有一个已连接的实例就没有可同步的目标、没有可测试的工作区也就无法验证应用是否真正可用。关于 Twenty 应用的工作原理packages/twenty-codex-plugin/references/concepts/how-apps-work.md 给出了更完整的背景Twenty 应用是拥有自己package.json、依赖和源码树的 npm 包运行时不作为独立服务而是被构建、发布并安装进运行中的 Twenty 实例由实例把实体加载进 schema、在 UI 中渲染前端组件。应用通常依赖两个 SDK 包包名用途典型导入入口twenty-sdk定义应用实体、访问前端组件运行时 API实体定义走twenty-sdk/definedefineApplication、defineObject、defineField、defineView、definePageLayout、defineFrontComponent、defineNavigationMenuItem、defineLogicFunction、defineRole等运行时 API 走twenty-sdk/front-componentnavigate、enqueueSnackbar、openSidePanelPage、useSelectedRecordIds、getApplicationVariable等twenty-client-sdk从前端组件访问工作区数据对象查询走twenty-client-sdk/coreCoreApiClient元数据查询走twenty-client-sdk/metadataUI 层使用twenty-ui包从 npm 安装twenty-ui1.0.0-alpha.1按子路径导入twenty-ui/input、twenty-ui/data-display、twenty-ui/icon等组件。第一步选择目标 Twenty 实例两种模式SKILL 默认要求先询问用户是否已有 Twenty 实例 URL如果没有则退化为本地 Docker 方案。两种方案的本质区别在于连接方式模式一已有的 Twenty 实例默认推荐用户提供运行中 Twenty 服务器的 URL自托管或云例如https://app.twenty.com。脚手架通过在该实例上执行OAuth完成认证——它会打开浏览器走 OAuth 流程随后把凭据作为remote存储到本地配置文件~/.twenty/config.json。该模式适合开发者已经拥有带数据的工作区、希望直接在其上进行开发的情况。模式二本地 Docker 实例兜底方案仅在用户没有可用的 Twenty 实例时使用。脚手架通过 Docker 启动一个一次性的本地 Twenty 服务默认地址http://localhost:2020用本地服务器的开发 API key 完成认证并自动创建一个名为local的 remote。该方案要求本机已安装并运行 Docker Desktop。使用原则若用户未提供 URL先询问是否已有实例 URL只有用户明确表示没有时才回退到 Docker。不要替用户默认选择。脚手架命令行参数详解目录命名规则脚手架对目录名有严格校验。在 cli.ts 中目录名必须匹配正则^[a-z0-9-]$——只能包含小写字母、数字与连字符。如果需要应把用户输入的名称转换为小写并将空格替换为连字符源码中通过lodash.kebabcase完成目录归一化参见 create-app.command.ts。若校验失败CLI 会打印错误并以非零码退出。完整参数表create-twenty-app的可执行入口位于 packages/create-twenty-app/src/cli.ts基于commander解析参数。全部 create-time 选项如下长选项短选项含义默认值 / 备注app-directory位置参数—项目目录名必须匹配^[a-z0-9-]$省略时以应用名 kebab-case 化生成--name name-n应用名写入package.json的name缺省取位置参数目录名再缺省为my-twenty-app不可为空字符串--display-name displayName-d展示名缺省由应用名转换而来见 convert-to-label.ts--description description—应用描述可省略--url url—Twenty 服务器 URL缺省为http://localhost:2020末尾斜杠会被去掉--api-url apiUrl—已废弃请改用--url传入会打印黄色警告--authentication-method method—oauth或apiKey默认本地用 apiKey、远程用 oauth详见下文基础命令形如# 已有 Twenty 实例默认走 OAuth 认证 npx create-twenty-applatest app-name --url twenty-instance-url # 没有实例本地 Docker 兜底省略 --url npx create-twenty-applatest app-name需要携带应用元数据时把所有信息一次性传入npx create-twenty-applatest app-directory \ --name package-name \ --display-name display-name \ --description description认证方式自动推导逻辑认证方式并不完全由参数决定。在 create-app.command.ts 中可以看到如下规则skipLocalInstance serverUrl ! DEV_API_URL即只要显式传入了非本地默认地址的--url就视为连接远程实例远程实例下即使显式传--authentication-method apiKey也会被忽略并自动切换到 OAuth并打印警告API key authentication is only supported on a local Docker instance本地实例下默认走apiKey使用开发专用 API key也可显式指定oauth。换言之apiKey 认证只存在于本地 Docker 开发环境任何远程/生产实例一律强制 OAuth。同时 CLI 在 cli.ts 会校验--authentication-method只能是oauth或apiKey二者之一。脚手架内部执行全流程源码级拆解CreateAppCommand.execute()把整个流程组织为若干带编号的步骤步骤总数由 computeTotalSteps 动态计算基础 4 步 本地场景多 1 步服务器启动 认证 1 步 同步 1 步。每一步内部都会打印进度并自动完成。结合 SKILL.md 与源码完整流水线如下校验与创建项目目录validateDirectory()检查目标目录不存在或为空fs.ensureDir()建目录。拷贝基础模板copyBaseApplicationProject()app-template.ts把仓库内置模板packages/create-twenty-app/src/constants/template复制到目标目录并把 npm 发布时会剥离的点文件gitignore→.gitignore、github→.github、yarnrc.yml→.yarnrc.yml改名还原同时把AGENTS.md镜像为CLAUDE.md。注入随机唯一标识符读取src/constants/universal-identifiers.ts把其中的DISPLAY-NAME-TO-BE-GENERATED、DESCRIPTION-TO-BE-GENERATED占位符替换为用户提供的展示名与描述把UUID-TO-BE-GENERATED逐一替换为uuid.v4()生成的稳定 UUID。更新package.json写入应用名并把twenty-sdk、twenty-client-sdk的 devDependency 版本锁定为create-twenty-app自身版本仓库中当前为 2.39.0见 package.json。安装依赖启用 corepack、执行依赖安装。初始化 GittryGitInit()尝试创建 Git 仓库与首次提交失败或已在仓库内时优雅跳过。仅本地模式启动 Twenty 服务ensureDockerServer()先在后台docker pull twentycrm/twenty-app-dev:latest再调用serverStart()拉起一次性容器Docker 未运行或拉取失败时给出提示并继续尽量用已有镜像。认证优先级为复用已有凭据→ 按推导出的认证方式执行。源码中tryExistingAuth()会扫描~/.twenty/config.json中所有 remote若存在 URL 匹配且 token 有效能通过/metadata的currentWorkspace查询的 remote直接复用并将其设为默认OAuth 路径authenticateWithOAuth()按服务器 hostname 派生 remote 名点号转连字符打开浏览器完成授权本地 apiKey 路径authenticateWithDevKey()使用开发 API key 认证为timapple.devremote 名为local。初始同步安装应用执行yarn twenty dev --once一次性同步命令。SKILL.md 特别强调脚手架已经执行过首次同步因此创建完成后不要为了验证而额外运行yarn twenty apply、yarn test、yarn lint。打开生成的欢迎页openMainPage()尽力解析工作区前端 URL 与占位页布局 ID 后在浏览器中打开best-effort失败不影响创建结果。若任一关键环节失败脚手架会打印可手动补救的提示例如Run yarn twenty dev --once manually.或Run yarn twenty remote:add --url your-instance-url manually.。成功结束时logSuccess()会输出后续步骤指引cd进入项目 → 若未认证成功则yarn twenty remote:add --url your-instance-url→yarn twenty dev开始开发 → 打开实例地址。脚手架产物的目录结构模板目录见 packages/create-twenty-app/src/constants/template。脚手架完成后一个典型应用项目结构如下my-app/ package.json # 应用元数据、版本、依赖已注入 twenty-sdk / twenty-client-sdk .github/workflows/ # CI / CD / Publish 自动化 src/ application-config.ts # defineApplication() —— 应用入口与身份声明 default-role.ts # 默认角色定义 constants/ universal-identifiers.ts # 全部实体的稳定 UUID脚手架生成严禁在首次同步后修改 front-components/ main-page.tsx # 占位主页面前端组件 page-layouts/ main-page.page-layout.ts # 占位页布局 navigation-menu-items/ main-page.navigation-menu-item.ts # 占位导航菜单项 public/ # 静态资源logo、截图、图片 AGENTS.md / CLAUDE.md # AI 协作约定互为镜像 SETUP.md / CHANGELOG.md / README.md其中 application-config.ts 调用defineApplication()引用src/constants/universal-identifiers.ts中生成的APPLICATION_UNIVERSAL_IDENTIFIER、APP_DISPLAY_NAME、APP_DESCRIPTION。Universal identifier通用唯一标识符是 Twenty 应用的关键设计每个实体都有稳定的 UUID它能在重命名、版本升级与重新同步中保持不变一旦首次同步后就不应再改动否则会破坏实例上已注册的实体与数据的对应关系。创建完成后哪些该做哪些不该做脚手架完成意味着应用已创建、已同步、已安装任务即告结束。SKILL.md 给出了清晰的收尾纪律不要在创建后运行任何多余的验证命令yarn twenty apply、yarn test、yarn lint等来证明脚手架成功——首次同步已由脚手架完成仅当用户明确要求时才执行测试且此时应切换到develop-app/manage-app的指导使用TWENTY_API_URLhttp://localhost:2021对隔离的测试实例运行完整测试套件。向用户报告应用创建成功、已可开始开发然后停止等待用户的下一步指令。此外要留意占位页面问题脚手架会自动生成一个占位页面src/front-components/main-page.tsx及其配套的页面布局和导航菜单项。在后续使用develop-app开发时除非应用确实需要 UI否则在首次部署前应把这三个文件全部删除并且不要在占位页面之上继续堆叠额外页面。这是避免把占位内容误部署到真实工作区的关键约定。Docker 兜底失败的排查仅当用户选择了本地 Docker 路径且失败原因是缺少 Docker 或 Docker 未运行时才进入本节排查流程。首选恢复方案向用户索取一个已有的 Twenty 实例 URL重新带--url twenty-instance-url运行脚手架——该路径完全跳过 Docker若用户仍坚持本地路径且 Docker 未安装引导其安装 Docker Desktop若 Docker 已安装但未启动ensureDockerServer 会打印提示并要求用户先启动 Docker 再重新运行命令运行前若检测到 Docker 完全缺失docker-install.ts 会按平台输出对应的安装指引并再次建议改用已有实例 URL 的方式。后续开发路径只有用户明确提出时才进入后续环节。SKILL.md 规划了清晰的衔接关系添加功能对象、字段、逻辑函数、角色、视图、导航、页面布局、Skills、Agents、前端组件注册→ 切换到 develop-app SKILL其配套参考包括 app-structure.md、data-model.md、front-components.md 等设计/打磨前端组件 UI→ 参考 front-component-ui.md同步实体变更到实例→ 后续对应用实体做任何改动后使用yarn twenty apply一键构建、部署并安装到当前 active remote完整同步工作流见 manage-app SKILL 及 cli-and-sync.md打包分享→yarn twenty app:publish发布到 npm公开市场或yarn twenty app:publish --private --remote name私有发布每次发布要求package.json中 semver 版本严格递增详见 publish-app SKILL 与 prepare-for-app-store.md。从全局视角看how-apps-work.md 把应用开发提炼为create → develop → sync → validate → repeat的生命周期循环create-twenty-app覆盖其中的Create环节yarn twenty apply承担Sync本地yarn twenty dev为开发态同步yarn twenty dev:typecheck负责类型检查浏览器打开工作区验证渲染与逻辑函数执行则对应Validate。理解这条循环就能明白为什么脚手架、同步与 Skill 边界会被设计成当前形态——所有命令最终都指向同一个目标让应用的实体与代码始终与某个运行中的 Twenty 实例保持一致。【免费下载链接】twentyThe open alternative to Salesforce, designed for AI.项目地址: https://gitcode.com/GitHub_Trending/tw/twenty创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考