upstream-twenty/packages/twenty-docs/l/ja/developers/extend/apps/getting-started/quick-start.mdx

---
title: クイックスタート
icon: rocket
description: 数分で最初の Twenty アプリを作成しましょう。
---

## 前提条件

* **Node.js 24.5+** — [こちらからダウンロード](https://nodejs.org/)
* **Yarn 4** — Corepack 経由で Node.js に同梱されています。 有効化: `corepack enable`
* **Docker** — [こちらからダウンロード](https://www.docker.com/products/docker-desktop/)。 ローカルの Twenty サーバーを実行するために必要です。 すでに別の場所で Twenty が稼働している場合はスキップしてください。

Twenty アプリの構築は 3 つのフェーズで構成されます。 スキャフォルダーはそれらをハッピーパスの 1 つのコマンドにまとめますが、各フェーズは別個の概念です — 何かが失敗したとき、いまどのフェーズにいるかが分かると、直すべき箇所が特定できます。

| フェーズ            | やること                    | ツール                                 | 結果                       |
| --------------- | ----------------------- | ----------------------------------- | ------------------------ |
| **1. スキャフォールド** | アプリのソースコードを生成する         | `npx create-twenty-app`             | ディスク上の TypeScript プロジェクト |
| **2. サーバーを起動**  | 同期先となる Twenty サーバーを起動する | Docker + `yarn twenty docker:start` | 稼働中の Twenty インスタンス       |
| **3. 同期**       | コードをサーバーにライブ同期する        | `yarn twenty dev`                   | 変更が UI に反映されます           |

---

## フェーズ 1 — プロジェクトをスキャフォールドする

テンプレートから新しいアプリを作成します:

```bash filename="Terminal"
npx create-twenty-app@latest my-twenty-app
```

スキャフォルダーは非対話型であり、ディレクトリ名がアプリ名になります。 生成されるメタデータをカスタマイズするには、`--display-name` と `--description` を指定します（後から `src/constants/universal-identifiers.ts` 内で編集することもできます）。 これにより、`my-twenty-app/` にスターターの `application-config.ts`、デフォルトロール、CI/CD ワークフロー、および統合テストを含む TypeScript プロジェクトが生成されます。

**このフェーズ後:** マシン上にアプリのソースコードがあります。 まだ実行はされていません — それはフェーズ 2 です。

---

## フェーズ 2 — ローカルの Twenty サーバーを起動する

アプリは同期先としての Twenty サーバーを必要とします。 サーバーは、UI、GraphQL API、PostgreSQL を備えた完全な Twenty インスタンスで、Docker 上でローカルに実行されます。 ローカルのコードは定義をそのサーバーにアップロードし、UI に反映されます。

スキャフォルダーが環境を自動的に起動します。Docker が動作している状態で、`twentycrm/twenty-app-dev` イメージを取得し、ポート `2020` で起動して、事前にデモデータが投入されたワークスペース（`tim@apple.dev`）に対して CLI を認証します — サインインは不要です。

既存の Twenty サーバーに接続する場合は、代わりに `--url \<your-server-url>` を指定してください。 リモートサーバーは OAuth で認証されます。ブラウザーが開き、サインインして **Authorize** をクリックすると、CLI にワークスペースへのアクセス権が付与されます。 （ローカルでも `--authentication-method oauth` を指定して OAuth を利用できます。その場合は `tim@apple.dev` / `tim@apple.dev` でサインインします。）

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/login.png" alt="Twenty のログイン画面" />
</div>

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/authorize.png" alt="Twenty CLI の承認画面" />
</div>

ターミナルにセットアップ完了のメッセージが表示されます。

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/scaffolded.png" alt="アプリのスキャフォルドに成功しました。" />
</div>

**このフェーズ後:** あなたの CLI が同期を許可された Twenty サーバーが [http://localhost:2020](http://localhost:2020) で稼働しています。

<Note>
Docker がインストールされていない、または起動していない場合、スキャフォルダーが OS に合った開始コマンドを案内します。 Docker が起動したら、`yarn twenty docker:start` で再開できます — 再スキャフォールドは不要です。
</Note>

---

## フェーズ 3 — 変更を同期する

ここが、最も多くの時間を費やす内側のループです。

```bash filename="Terminal"
cd my-twenty-app
yarn twenty dev
```

これは `src/` を監視し、変更のたびに再ビルドして、その結果をサーバーに同期します。 ファイルを編集して保存すると、数秒以内にサーバーに変更が反映されます。 ターミナルにライブステータスパネルが表示されます。

より詳細な出力（ビルドログ、同期リクエスト、エラートレース）が必要な場合は、`--verbose` フラグを使用します。

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/dev.png" alt="開発モードのターミナル出力" />
</div>

ブラウザーで [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer) を開きます。 **Your Apps** にアプリが表示されるはずです。

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="Your Apps リストに My twenty app が表示されている様子" />
</div>

**My twenty app** をクリックすると、その **application registration**（アプリを記述するサーバーレベルのレコード。名前、識別子、OAuth 認証情報、ソース）が表示されます。 同一サーバー上では、1 つの登録を複数のワークスペースにインストールできます。

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="アプリケーション登録の詳細" />
</div>

ワークスペースへのインストールを確認するには **View installed app** をクリックします。 **About** タブには現在のバージョンと管理オプションが表示されます。

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="インストール済みのアプリ" />
</div>

**このフェーズ後:** ライブな開発ループが確立しています。 `src/` 内の任意のファイルを編集すると、UI に反映されます。

### CI やスクリプト向けの一回限りの同期

ウォッチャーなしで同じパイプラインを 1 回だけ実行するには、`plan` と `apply` を使用します。

```bash filename="Terminal"
yarn twenty plan   # preview the metadata changes without applying them
yarn twenty apply  # show the plan, then apply it
```

| コマンド                | 動作                                                                                          | 使用する場面                                       |
| ------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `yarn twenty dev`   | ソースファイルを監視し、変更のたびに再同期します。 停止するまで実行し続けます。                                                    | 対話的なローカル開発。                                  |
| `yarn twenty apply` | ビルドと同期を一度だけ実行し、成功時はコード `0`、失敗時は `1` で終了します。 破壊的な変更がある場合に確認を求めます（スキップするには `--force` を指定します）。 | CI、pre-commit フック、AI エージェント、スクリプト化されたワークフロー。 |
| `yarn twenty plan`  | メタデータの変更をビルドして出力しますが、**実際には適用しません**。                                                        | 同期によってどのような変更が行われるかを、実行を確定する前に確認します。         |

すべてのモードで、認証済みのリモートが必要です。 `plan` の詳細については、[Syncing & recovery](/l/ja/developers/extend/apps/operations/sync-and-recovery#previewing-changes-plan) を参照してください。

<Note>
`yarn twenty dev --once` および `yarn twenty dev --once --dry-run` は非推奨であり、それぞれ `yarn twenty apply` および `yarn twenty plan` のエイリアスです。
</Note>

### Dev モードのオプション

| フラグ                                   | 説明                                        |
| ------------------------------------- | ----------------------------------------- |
| `--force`                             | 確認なしで破壊的な変更（削除）を適用します。                    |
| `--debounceMs \<ms>` | ファイル変更のデバウンス遅延をミリ秒単位で設定します (既定値: `1000`)。 |
| `--verbose` / `--debug`               | 詳細なビルドログ、同期リクエスト、およびエラートレースを表示します。        |

## 構築できるもの

アプリは**エンティティ**で構成されており、それぞれが単一の `export default` を持つ TypeScript ファイルとして定義されます:

| エンティティ           | 機能                                                               |
| ---------------- | ---------------------------------------------------------------- |
| **オブジェクトとフィールド** | カスタムデータモデル（ポストカード、請求書など） 型付きフィールド                                |
| **ロジック関数**       | HTTP ルート、cron スケジュール、またはデータベースイベントによってトリガーされるサーバーサイドの TypeScript |
| **フロントコンポーネント**  | Twenty の UI（サイドパネル、ウィジェット、コマンドメニュー）内でレンダリングされる React コンポーネント     |
| **スキルとエージェント**   | AI 機能 — 再利用可能な指示と自律型アシスタント                                       |
| **ビューとナビゲーション**  | 事前設定済みのリストビューとサイドバーのメニュー項目                                       |
| **ページレイアウト**     | タブとウィジェットを備えたカスタムのレコード詳細ページ                                      |

完全なリファレンス: [Concepts](/l/ja/developers/extend/apps/getting-started/concepts)。

## 次のステップ

<CardGroup cols={2}>
  <Card title="設定" icon="screwdriver-wrench" href="/l/ja/developers/extend/apps/config/overview">
    アプリケーション ID、デフォルトロール、インストールおよびアンインストールフック、公開アセット。
  </Card>
  <Card title="データ" icon="database" href="/l/ja/developers/extend/apps/data/overview">
    オブジェクト、フィールド、および双方向リレーション。
  </Card>
  <Card title="ロジック" icon="bolt" href="/l/ja/developers/extend/apps/logic/overview">
    ロジック関数、スキル、エージェント、および OAuth 接続。
  </Card>
  <Card title="レイアウト" icon="table-columns" href="/l/ja/developers/extend/apps/layout/overview">
    ビュー、ナビゲーション、ページレイアウト、フロントコンポーネント。
  </Card>
  <Card title="オペレーション" icon="rocket" href="/l/ja/developers/extend/apps/operations/overview">
    CLI、テスト、リモート、CI、およびアプリの公開。
  </Card>
</CardGroup>