前提条件
- Node.js 24+ — こちらからダウンロード
- Yarn 4 — Corepack 経由で Node.js に同梱されています。 有効化:
corepack enable - Docker — こちらからダウンロード。 ローカルの Twenty サーバーを実行するために必要です。 すでに別の場所で Twenty が稼働している場合はスキップしてください。
| フェーズ | やること | ツール | 結果 |
|---|---|---|---|
| 1. スキャフォールド | アプリのソースコードを生成する | npx create-twenty-app | ディスク上の TypeScript プロジェクト |
| 2. サーバーを起動 | 同期先となる Twenty サーバーを起動する | Docker + yarn twenty server | 稼働中の Twenty インスタンス |
| 3. 同期 | コードをサーバーにライブ同期する | yarn twenty dev | 変更が UI に反映されます |
フェーズ 1 — プロジェクトをスキャフォールドする
テンプレートから新しいアプリを作成します:my-twenty-app/ にスターターの application-config.ts、デフォルトロール、CI ワークフロー、統合テストを含む TypeScript プロジェクトが生成されます。
このフェーズ後: マシン上にアプリのソースコードがあります。 まだ実行はされていません — それはフェーズ 2 です。
フェーズ 2 — ローカルの Twenty サーバーを起動する
アプリは同期先としての Twenty サーバーを必要とします。 サーバーは、UI、GraphQL API、PostgreSQL を備えた完全な Twenty インスタンスで、Docker 上でローカルに実行されます。 ローカルのコードは定義をそのサーバーにアップロードし、UI に反映されます。 スキャフォルダーが起動を提案します:ローカルの Twenty インスタンスをセットアップしますか？
- Yes（推奨） —
twentycrm/twenty-app-devDocker イメージを取得し、ポート2020で起動します。 まず Docker が起動していることを確認してください。 - No — すでに接続したい Twenty サーバーがある場合に選択します。 後で
yarn twenty remote:addで接続を設定できます。
- メールアドレス:
tim@apple.dev - パスワード:
tim@apple.dev
Docker がインストールされていない、または起動していない場合、スキャフォルダーが OS に合った開始コマンドを案内します。 Docker が起動したら、
yarn twenty docker:start で再開できます — 再スキャフォールドは不要です。フェーズ 3 — 変更を同期する
ここが、最も多くの時間を費やす内側のループです。src/ を監視し、変更のたびに再ビルドして、その結果をサーバーに同期します。 ファイルを編集して保存すると、数秒以内にサーバーに変更が反映されます。 ターミナルにライブステータスパネルが表示されます。
より詳細な出力（ビルドログ、同期リクエスト、エラートレース）が必要な場合は、--verbose フラグを使用します。
src/ 内の任意のファイルを編集すると、UI に反映されます。
CI やスクリプト向けの一回限りの同期
単一のビルド＋同期を実行して終了するには--once を指定します — パイプラインは同じでウォッチャーはありません:
| コマンド | 動作 | 使用する場面 |
|---|---|---|
yarn twenty dev | ソースファイルを監視し、変更のたびに再同期します。 停止するまで実行し続けます。 | 対話的なローカル開発。 |
yarn twenty dev --once | ビルドと同期を一度だけ実行し、成功時はコード 0、失敗時は 1 で終了します。 | CI、pre-commit フック、AI エージェント、スクリプト化されたワークフロー。 |
yarn twenty dev --once --dry-run | メタデータの変更をビルドして出力しますが、実際には適用しません。 | 同期によってどのような変更が行われるかを、実行を確定する前に確認します。 |
--dry-run について詳しくは、Syncing & recovery を参照してください。
Dev モードのオプション
| フラグ | 説明 |
|---|---|
--once | 一度ビルドと同期を実行したら終了します。 |
--dry-run | --once を使用すると、メタデータの変更を適用せずにプレビューできます。 何も書き込みません。 |
--debounceMs \<ms> | ファイル変更のデバウンス遅延をミリ秒単位で設定します (既定値: 2000)。 |
--verbose / --debug | 詳細なビルドログ、同期リクエスト、およびエラートレースを表示します。 |
構築できるもの
アプリはエンティティで構成されており、それぞれが単一のexport default を持つ TypeScript ファイルとして定義されます:
| エンティティ | 機能 |
|---|---|
| オブジェクトとフィールド | カスタムデータモデル（ポストカード、請求書など） 型付きフィールド |
| ロジック関数 | HTTP ルート、cron スケジュール、またはデータベースイベントによってトリガーされるサーバーサイドの TypeScript |
| フロントコンポーネント | Twenty の UI（サイドパネル、ウィジェット、コマンドメニュー）内でレンダリングされる React コンポーネント |
| スキルとエージェント | AI 機能 — 再利用可能な指示と自律型アシスタント |
| ビューとナビゲーション | 事前設定済みのリストビューとサイドバーのメニュー項目 |
| ページレイアウト | タブとウィジェットを備えたカスタムのレコード詳細ページ |
次のステップ
設定
アプリケーション ID、デフォルトロール、インストールフック、公開アセット。
データ
オブジェクト、フィールド、および双方向リレーション。
ロジック
ロジック関数、スキル、エージェント、および OAuth 接続。
レイアウト
ビュー、ナビゲーション、ページレイアウト、フロントコンポーネント。
オペレーション
CLI、テスト、リモート、CI、およびアプリの公開。