github-actions[bot]
ebee7d71b9
Created by Github action <!-- This is an auto-generated description by cubic. --> <a href="https://cubic.dev/pr/twentyhq/twenty/pull/22715?utm_source=github" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img alt="Review in cubic" src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a> <!-- End of auto-generated description by cubic. --> Co-authored-by: github-actions <github-actions@twenty.com>
167 lines
12 KiB
Plaintext
167 lines
12 KiB
Plaintext
---
|
|
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>
|