どのコマンドをいつ使うか
日々のローカルでの反復開発では、ほとんどの場合
yarn twenty dev を使うことになります。 デプロイと公開はリリースのためのものであり、ローカルでの開発ループのためのものではありません。| やりたいこと… | コマンド | ノート |
|---|---|---|
| ライブ同期でローカルに反復開発する | yarn twenty dev | ファイルを監視し、変更のたびに同期します。 |
| 1 回だけ同期して終了（CI、スクリプト、フック向け） | yarn twenty apply | 1 回ビルドして同期し、その後終了します。 破壊的変更の確認をスキップするには、--force を追加します。 |
| 変更を適用せずにプレビュー | yarn twenty plan | 差分を計算して表示しますが、何も書き込みません。 |
| ワークスペースからアプリを削除する | yarn twenty app:uninstall | プロンプトをスキップするには、--yes を追加します。 |
| サーバーに tarball をアップロードする | yarn twenty app:publish --private | package.json のバージョンが厳密により高い必要があります — Publishing を参照してください。 |
| マーケットプレイス（npm）に公開する | yarn twenty app:publish | — |
| デプロイ済みバージョンをインストール / アップグレードする | yarn twenty app:install | 現在デプロイされているバージョンをインストールします。 |
| ローカルサーバーを消去してクリーンに開始する | yarn twenty docker:reset | ローカルデータをすべて削除します — 最終手段です。 |
yarn twenty dev --once および yarn twenty dev --once --dry-run は、yarn twenty apply と yarn twenty plan の非推奨エイリアスとして依然として動作します。ローカル同期ではバージョンの更新は不要
厳密に増加するversion のルール（デプロイ時の VERSION_ALREADY_EXISTS、インストール時の APP_ALREADY_INSTALLED / CANNOT_DOWNGRADE_APPLICATION）は、リリースパスである app:publish / app:install に適用されます。 yarn twenty dev はマニフェストをその場で同期し、バージョン変更を要求することはないため、反復するのに package.json を触る必要はありません。 ローカルの変更をテストするためにバージョンを上げている場合は、開発ループが必要なところでリリース経路を使ってしまっています。
同期出力の読み方
各同期では、適用した（plan の場合は適用される）メタデータの変更が出力されます。Terraform と同様に、エンティティごとにその属性を含むブロックが 1 つずつ表示され、その後にサマリー行が続きます。
to destroy）は、何を削除するかとあわせて一覧表示され（例: objectMetadata "auditNote" — drops the table and all its rows）、対話的な確認、またはスクリプト内での --force が必要です。
同期が単一のエンティティで失敗した場合、エラーには問題のエンティティとその universalIdentifier が、次のように示されます。
変更内容のプレビュー（プラン）
yarn twenty plan はマニフェストをビルドし、サーバーにマイグレーションプランを問い合わせ、その内容を 何も適用せずに 表示します。 コミットする前に「この同期は何を変更するか？」という問いに安全に答える方法です。
- 何も書き込みません — メタデータマイグレーション、アプリケーションレコードの更新、デフォルトのロール / タブの変更、API クライアントの生成は一切行いません。
- 実際の同期が適用するのと同じ差分を返すため、作成 / 更新 / 削除されるエンティティを事前に確認できます。
- リスクの高い変更の前や、AI 生成の変更をレビューするとき、または予期せぬ変更が行われそうな場合にスクリプトを失敗させたいときなどに有用です。
プランでは メタデータ の変更のみがプレビューされます。また、アプリが少なくとも一度は同期されている（ワークスペース側がその存在を知っている）必要があります。 一度も同期されていないアプリに対して実行すると、サーバーはそのアプリがインストールされていないと報告します — まず一度
yarn twenty dev を実行してください。リカバリーラダー
ローカルのメタデータが正しくないように見える場合は、次の順番でエスカレートし、問題が解消したところで止めてください。 各ステップは前のものよりも影響が大きくなります。- 再同期。
yarn twenty applyを再度実行します。 同期はべき等であり、クリーンなマニフェストを再実行しても安全で、多くの場合は一時的な不具合が解消されます。 - プランをプレビュー。
yarn twenty planを実行して、次の同期が何を変更しようとしているのかを、適用せずに正確に確認します。 - 名前付きエラーを読む。 同期が失敗した場合は、メッセージ内のメタデータタイプと
universalIdentifier（上記参照）を確認し、そのエンティティをマニフェスト内で特定します。 コンフリクトは、重複または再利用された識別子を指していることがほとんどです。 - アンインストールして再インストール。
yarn twenty app:uninstallを実行し、その後再度同期します（yarn twenty dev）。 これにより、ワークスペースの残りを維持したまま、アプリのメタデータをクリーンな状態から再構築します。 - フルリセット（最後の手段）。
yarn twenty docker:resetを実行し、その後再シードと再同期を行います。
メタデータエラーが発生しましたか？ issue を作成し、失敗したマイグレーションメッセージ（メタデータタイプと
universalIdentifier を含む）、同期時の Metadata changes の出力、および実行したコマンドを記載してください。1 つのワークスペースでの同時同期を避ける
同期ではメタデータマイグレーションが適用されます。 同じワークスペースに対して同時に複数の同期、デプロイ、インストール操作を実行すると（たとえば、複数のターミナルや AI エージェントが並行して反復している場合）、それらのマイグレーションが入り混じり、メタデータが一部だけ適用された状態のままになってしまう可能性があります。 サーバーはワークスペースごとに同期を直列化してこれを防いでいますが、それでも、センシティブなメタデータ操作は同時に実行するのではなく、単一のプロセスに集約するべきです。 複数のエージェントで開発をオーケストレーションしている場合は、それらの sync / deploy / install 呼び出しを 1 つのキューに流し込み、同時ではなく一度に 1 つだけ実行されるようにしてください。失敗の切り分け
問題が発生したときは、メタデータの差分と名前付きエラーによって、どこで失敗したかを特定できます。- マニフェストビルドエラー — CLI が同期前に失敗します（
MANIFEST_BUILD_FAILED、TYPECHECK_FAILED）。アプリのソースを修正してください。 - 同期 / マイグレーションエラー — ビルドは成功しますが、差分の適用が失敗し、エンティティと
universalIdentifierが示されます。そのコンフリクトしているメタデータを修正してください。 - アプリコードの実行時エラー — 同期自体は成功しているものの、ロジック関数やコンポーネントが実行時に正しく動作しません。function logs を確認してください。
- ローカルインスタンスの状態 — 上記のいずれにも当てはまらないのにワークスペースの見た目が依然としておかしい場合は、リカバリーラダーに従って下の段階へ進んでください。