nx-generate

Nx ジェネレーターの実行

Nx ジェネレーターは、プロジェクトのひな形を作成したり、自動コード移行を行ったり、モノレポ内の反復作業を自動化したりする強力なツールです。コードベース全体の一貫性を確保し、定型コードの作業を減らします。

このスキルは、ユーザーが次のことを希望する場合に適用されます。

• ライブラリやアプリケーションなどの新しいプロジェクトを作成する
• 機能や定型コードのひな形を作成する
• ワークスペース固有のジェネレーターやカスタムジェネレーターを実行する
• Nx ジェネレーターで実行できるその他の作業を行う

ジェネレーターの検索フロー

ステップ 1：利用可能なジェネレーターを一覧表示する

Nx CLI を使用して、利用可能なジェネレーターを確認します。

• プラグインのすべてのジェネレーターを一覧表示する：npx nx list @nx/react
• 利用可能なプラグインを表示する：npx nx list

次のものが含まれます。

• プラグインのジェネレーター（例：@nx/react:library、@nx/js:library）
• ローカルワークスペースのジェネレーター（リポジトリ独自のプラグインで定義されているもの）

ステップ 2：ジェネレーターをユーザーの依頼に合わせる

ユーザーの依頼に基づいて、要件を満たせるジェネレーターを特定します。次の点を考慮してください。

• 作成したい成果物の種類（ライブラリ、アプリケーションなど）
• 関連するフレームワークや技術スタック
• 特定のジェネレーター名が指定されているか

重要：ローカルワークスペースのジェネレーターと外部プラグインのジェネレーターの両方で依頼に対応できる場合は、必ずローカルワークスペースのジェネレーターを優先してください。ローカルジェネレーターは、特定のリポジトリのパターンや規約に合わせてカスタマイズされています。

Nx ジェネレーターではまったく対応できない依頼もあり得ます。その場合は、このスキルの使用を中止し、別の方法でユーザーを支援できます。ただし、その判断には十分な根拠が必要です。中止する前に、利用可能なジェネレーターを一つ残らず慎重に検討してください。少しでも関連する可能性があるジェネレーターについては、判断を下す前に詳細を確認してください。

実行前のチェックリスト

ジェネレーターを実行する前に、次の手順を完了してください。

1. ジェネレーターのスキーマを取得する

--help フラグを使用して、利用可能なすべてのオプションを確認します。

npx nx g @nx/react:library --help

次の点に注意してください。

• 指定が必須のオプション
• ユーザーの依頼に関連する可能性があるオプション
• 上書きが必要な場合があるデフォルト値

2. ジェネレーターのソースコードを読む

ジェネレーターが実際に何を行うかを理解すると、次のことができます。

• 作成または変更されるファイルを把握する
• 副作用（設定の更新、依存関係のインストールなど）を理解する
• スキーマからは分かりにくいオプションを特定する

ジェネレーターのソースコードを見つけるには、次の方法を使用します。

• プラグインのジェネレーターの場合：node -e "console.log(require.resolve('@nx/<plugin>/generators.json'));" を使用して generators.json を見つけ、そこからソースを探します
• 上記の方法で見つからない場合は、node_modules/<plugin>/generators.json を直接読みます
• ローカルジェネレーターの場合：通常は tools/generators/ またはローカルプラグインのディレクトリにあります。リポジトリ内でジェネレーター名を検索して見つけられます。

2.5 ジェネレーターが適切か再評価する

選択したジェネレーターの動作を把握したら、ユーザーの依頼に適したジェネレーターかどうかを改めて検討します。 適切でない場合は、実行に進む前に「ジェネレーターの検索フロー」に戻り、別のジェネレーターを選んでもかまいません。その場合は、実行前のチェックリストを最初から最後まで再度確認してください。

3. リポジトリの状況を把握する

生成する前に、コードベース内の対象領域を調べます。

• 類似する既存の成果物（他のライブラリ、アプリケーションなど）を確認する
• リポジトリで使用されているパターンや規約を特定する
• 命名規則、ファイル構成、設定パターンを確認する
• ジェネレーターの設定時に、これらのパターンに合わせるようにする

たとえば、類似するライブラリで特定のテストランナー、ビルドツール、またはリンターを使用している場合は、可能であればそれに合わせてください。 プロジェクトやその他の成果物が特定の命名規則に従って整理されている場合は、その規則に合わせてください。

4. 必須オプションを確認する

すべての必須オプションに値が設定されていることを確認します。

• ユーザーのリクエストをジェネレーターのオプションに対応付けます
• 可能な場合は、コンテキストから値を推測します
• 重要な情報が不足している場合は、ユーザーに確認します

実行

ユーザーが nx をグローバルにインストールしていない場合は、コマンドの前に npx/pnpx/yarn を付ける必要があるかもしれないことに留意してください。 多くのジェネレーターは、実行場所によって動作が異なります。たとえば、Nx のファーストパーティ製ライブラリジェネレーターは、ライブラリを配置するディレクトリを判断するために cwd を使用します。これは非常に重要です。

ドライランを検討する（任意）

まず --dry-run を実行することを強く推奨しますが、必須ではありません。状況に応じて判断してください。

• 複雑なジェネレーターや不慣れな作業では、先にドライランを実行します
• 単純で十分に理解しているジェネレーターでは、そのまま実行してもかまいません
• ドライランではファイル名と作成／削除／変更のマーカーが表示されますが、内容は表示されません
• ジェネレーターがドライランに対応していない場合もあります（たとえば、npm パッケージをインストールする必要がある場合など）。その場合、--dry-run は失敗することがあります。気にせず、実際にジェネレーターを実行し、そこから反復してください。

ジェネレーターの実行

次のコマンドでジェネレーターを実行します。

nx generate <generator-name> <options> --no-interactive

重要：実行がプロンプト待ちで停止しないよう、必ず --no-interactive を指定してください。

例：

nx generate @nx/react:library --name=my-utils --no-interactive

ジェネレーターの失敗への対処

ジェネレーターが失敗した場合：

1. エラーを診断する - エラーメッセージを注意深く読みます
2. 原因を特定する - オプションの不足、無効な値、競合などを確認します
3. 自動修正を試みる - オプションを調整するか、競合を解消します
4. 再試行する - 修正したオプションでジェネレーターを再実行します

よくある失敗の原因：

• 必須オプションの不足
• 無効なオプション値
• 既存ファイルとの競合
• 依存関係の不足
• ジェネレーターが特定のフラグの組み合わせに対応していない

生成後

1. 生成されたコードを変更する（必要な場合）

ジェネレーターは出発点となるコードを提供しますが、ユーザー固有の要件に合わせて出力を調整する必要がある場合があります。

• リクエストに応じて機能を追加または変更します
• インポート、エクスポート、または設定を調整します
• リポジトリ内の既存のコードパターンに統合します

2. コードをフォーマットする

生成／変更したすべてのファイルにフォーマットを実行します。

nx format --fix

JavaScript／TypeScript 以外の言語では、別のフォーマットコマンドが必要な場合もあります。

3. 検証を実行する

生成されたコードが正しく動作することを検証します。検証方法は、ジェネレーターの種類や利用可能なターゲットによって異なります。 新しいプロジェクトが生成された場合は、そのターゲットを直接実行します。 何を検証すべきか、最善の判断をしてください。

例：

nx lint <new-project>
nx test <new-project>
nx build <new-project>

4. 検証失敗に対処する

検証に失敗した場合：

対応範囲が小さい場合（少数の lint エラー、軽微な型の問題など）：

• 問題を修正します
• 検証を再実行し、解決したことを確認します

問題が広範囲に及ぶ場合（多数のエラー、複雑な問題など）：

• まず、簡単で明白な修正を試みます
• それでも失敗する場合は、次の情報をユーザーに伝えて対応を依頼します。
  • 生成された内容の説明
  • 失敗している検証
  • 修正のために試みたこと
  • ユーザーの入力が必要な未解決の問題

エラー処理

ジェネレーターの失敗

• エラーメッセージを確認し、具体的な原因を特定します
• すべての必須オプションが指定されていることを確認します
• 既存ファイルとの競合を確認します
• ジェネレーター名とオプションが正しいことを確認します

オプションの不足

• 必須フィールドについて、ジェネレーターのスキーマを確認します
• 妥当な場合は、コンテキストから値を推測します
• 推測できない値はユーザーに確認します

主な原則

1. ローカルのジェネレーターを優先 - どちらでも対応できる場合は、外部プラグインのジェネレーターよりも、ワークスペースまたはローカルのジェネレーターを常に優先してください

2. 実行する前に理解する - 実行時の動作を十分に把握できるよう、スキーマとソースコードの両方を読んでください

3. プロンプトを表示しない - 処理が停止しないよう、常に --no-interactive を使用してください

4. ジェネレーターは出発点 - ユーザーの要件を完全に満たすよう、必要に応じて生成された出力を変更してください

5. 変更が機能することを確認 - 生成するだけでなく、コードのビルド、リント、テストが成功することを確認してください

6. 積極的に修正する - エラーを報告するだけでなく、可能であれば自動的な解決を試みてください

7. リポジトリのパターンに合わせる - リポジトリ内にある既存の類似コードを調べ、その規約に合わせてください