Twenty 应用脚手架模板 README 详解从 create-twenty-app 生成到 npm 可信发布【免费下载链接】twentyThe open alternative to Salesforce, designed for AI.项目地址: https://gitcode.com/GitHub_Trending/tw/twenty本文以create-twenty-app脚手架内置的应用模板 README 为骨架逐节解读一个新建 Twenty 应用工程文档的组织方式Features、Getting started本地开发环境搭建、Publishing基于 npm trusted publishing 的带来源证明发布、Changelog四个章节各自对应的工程文件与命令并结合仓库中的脚手架源码目录复制、dotfiles 改名、UUID 生成、package.json 改写与 GitHub Actions 工作流说明这套模板从脚手架落地到发布 npm 的完整链路。读完后你能独立复现一个可发布 Twenty 应用工程并理解其 CI/CD 与发布流程的每个配置项。模板 README 的位置与生成机制模板 README 位于packages/create-twenty-app包的src/constants/template/目录下它不是一份静态文档而是create-twenty-appCLI 创建应用时整体复制到用户目录的模板文件之一。同目录下的 SETUP.md、CHANGELOG.md、package.json、AGENTS.md 以及src/、public/、github/workflows/等文件共同构成一个可运行的最小应用骨架。从 脚手架源码 可以看到执行create-twenty-app后的核心步骤依次是创建项目目录、调用copyBaseApplicationProject拷贝模板、安装依赖、初始化 Git。而模板拷贝的细节实现在 app-template.ts整目录复制fs.copy将template/全量复制到目标目录dotfiles 改名由于 npm 发布包时会剥离点文件模板中.gitignore、.github/、.yarnrc.yml在仓库里以gitignore、github、yarnrc.yml的无点形式存放复制后再统一改回带点名称见 renameDotfiles生成唯一标识将src/constants/universal-identifiers.ts中的DISPLAY-NAME-TO-BE-GENERATED、DESCRIPTION-TO-BE-GENERATED、UUID-TO-BE-GENERATED每个占位符替换为新的 UUID v4替换为实际应用值改写 package.json把包名TO-BE-GENERATED换成应用名并将twenty-sdk、twenty-client-sdk的版本锁定为create-twenty-app自身版本见 updatePackageJson。模板 README 因此是「每个新应用出生时自带的第一份文档」它约定了应用工程后续应维护的四类内容。章节一Features —— 应用功能清单模板要求开发者用一两句话描述应用并列出核心功能Feature one / two / three为占位项。这一节没有对应代码纯粹是面向应用市场或协作者的说明性内容但它是发布到 Twenty 应用市场前最基本的自述材料。章节二Getting started —— 本地开发环境搭建README 将安装说明外置到SETUP.md模板中的 SETUP.md 给出了完整的本地运行步骤这也是脚手架跑通后的实际验证路径。前置条件Node.js模板 package.json 中engines声明为^24.5.0npm字段写死please-use-yarnyarn要求4.0.2即强制使用 Yarn 4Docker用于拉起本地 Twenty 服务器。操作步骤# 1. 安装依赖 yarn install # 2. 启动本地 Twenty 服务器Docker yarn twenty docker:start # 随时可用 yarn twenty docker:status 查看状态 # 3. 启动开发服务器并同步应用 yarn twenty dev然后打开http://localhost:2020使用默认开发账号timapple.dev/timapple.dev登录。这里与脚手架行为可以互相印证create-twenty-app在交互流程中已经会自动完成「启动 Docker 服务 → 认证开发 API key即timapple.dev对应凭证→ 执行yarn twenty dev --once同步应用 → 打开应用欢迎页」的链路见 create-app.command.ts 的 execute 流程 与 syncApplication。也就是说SETUP.md是 CLI 自动化流程失败时的手动兜底路径。工程自检命令模板package.json的scripts定义了四个常用脚本SETUP.md将其归纳为「验证环境是否搭好」的检查清单脚本命令用途yarn lintoxlint -c .oxlintrc.json .使用 oxlint 做静态检查yarn typechecktsgo --noEmit -p tsconfig.spec.json基于 TypeScript native preview 做类型检查yarn test:unitvitest run --config vitest.unit.config.ts仅跑单元测试vitest.unit.config.tsyarn testvitest run跑集成测试需要连到 Twenty 实例模板的 application-config.test.ts 与 schema.integration-test.ts 就是这两类测试的基线示例。章节三Publishing —— 基于 npm trusted publishing 的发布这是模板 README 中最具技术含量的部分。README 指出Publish工作流.github/workflows/publish.yml会把应用发布到 npm 并附带来源证明provenance依赖 npm trusted publishing其完整配置为name: Publish on: push: tags: - v* workflow_dispatch: permissions: contents: read # Required for npm trusted publishing (OIDC provenance). id-token: write jobs: publish: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 - name: Setup Node.js uses: actions/setup-nodev4 with: node-version: 24 registry-url: https://registry.npmjs.org - name: Update npm # Trusted publishing requires npm 11.5.1 or later. run: npm install -g npmlatest - name: Install dependencies run: yarn install --immutable - name: Publish to npm # Uncomment if publishing from a private source repo: npm rejects # OIDC provenance for private repos # env: # TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: true run: yarn twenty app:publish对照 README 中的发布步骤逐项解读第 1 步在 npmjs.com 注册可信发布源。在包的 Settings Trusted Publisher 页面把该仓库与publish.yml工作流登记为可信发布源。这正是工作流里permissions: id-token: write的用途——OIDC token 让 npm 校验「这次发布请求确实来自 GitHub Actions 的某条可信工作流」全程无需保存NPM_TOKEN。工作流注释中明确写出这是 Required for npm trusted publishing (OIDC provenance)。第 2 步打版本 tag 或手动触发。两个触发器与之对应push: tags: v*例如git tag v1.0.0 git push --tags和workflow_dispatchActions 页面手动运行。发布命令是yarn twenty app:publishyarn install --immutable保证依赖锁文件不被修改npm install -g npmlatest则是因为可信发布要求 npm 11.5.1 及以上版本。私有仓库的特殊处理工作流注释提示若应用源码仓库为私有需取消TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: true的注释——因为 npm 不接受来自私有仓库的 OIDC provenance此时只能关闭来源证明发布。Provenance 与所有权声明README 最后强调provenance 证书的是「这个 npm 包由哪个 GitHub 仓库构建」这同时也是在 Twenty 应用市场marketplace申请认领应用时证明所有权的方式——认领流程会校验你拥有 provenance 所指向的 GitHub 账号或组织publish.yml 头部注释 对此有同样说明。章节四Changelog 与 Learn more模板 CHANGELOG.md 初始化时只有一条记录0.1.0 - Initial application scaffolded with create-twenty-app与package.json中初始version: 0.1.0对应约定后续每次发版在文件内追加变更说明。Learn more部分在仓库内的对应资源包括应用开发文档本仓库packages/twenty-docs/developers/extend/下收录了完整的 Twenty Apps 开发文档.mdx其中 应用扩展总览目录 覆盖 config、data、logic、layout、operations 各主题可参考的完整示例postcard 示例应用 是功能最齐全的参考工程含e2e/、CLAUDE.md、完整src/布局模板 AGENTS.md 也将其列为 rich app example实体生成命令模板AGENTS.md列出了yarn twenty dev:add entity全量命令表object、field、logicFunction、frontComponent、role、view、navigationMenuItem、pageLayout 等 15 类实体是开发阶段替代手写骨架的标准做法。配套 CI/CD模板自带的质量与部署工作流README只直接引用了publish.yml但模板 github/workflows/ 目录还内置了两个工作流构成完整的工程闭环简要说明其与文档章节的关系ci.yml在 push 到main或 PR 时先用spawn-twenty-app-dev-testaction 拉起一个测试用 Twenty 实例TWENTY_VERSION: latest再依次执行yarn lint、yarn typecheck、yarn test:unit、yarn test后者注入TWENTY_API_URL与TWENTY_API_KEY——这正对应SETUP.md中「Verifying your setup」四条命令在云端的重放cd.ymlpush 到main或 PR 打上deploy标签时通过deploy-twenty-app/install-twenty-appaction 将应用部署并安装到TWENTY_DEPLOY_URL默认http://localhost:2020可用仓库 secretTWENTY_DEPLOY_API_KEY指向远端实例实现「合入即部署」的持续交付。小结模板 README 虽然只有几十个词但它锚定了create-twenty-app脚手架产出工程的全部关键文档面Features面向市场与协作者的功能自述Getting started→ SETUP.mdNode 24 Yarn 4 Docker 的本地环境yarn twenty docker:start/yarn twenty dev两步启动lint/typecheck/test:unit/test四道自检Publishing→ publish.ymlnpm trusted publishingid-token: write npm ≥ 11.5.1 v*tag 触发provenance 同时服务供应链溯源与 marketplace 所有权认领Changelog/Learn more版本变更记录起点与官方文档、示例应用的入口。配合ci.yml、cd.yml两个内建工作流新建的 Twenty 应用在git tag v1.0.0之后即可走通「CI 质量门禁 → 部署 → 带来源证明发布」的完整交付链路。【免费下载链接】twentyThe open alternative to Salesforce, designed for AI.项目地址: https://gitcode.com/GitHub_Trending/tw/twenty创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考