nx-generate

Nx ジェネレーターの実行

Nx ジェネレーターは、プロジェクトの雛形生成、自動コードマイグレーション、モノレポ内の反復作業の自動化を行う強力なツールです。コードベース全体の一貫性を保ち、ボイラープレート作業を削減します。

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

• ライブラリやアプリケーションなどの新しいプロジェクトを作成する
• 機能やボイラープレートコードの雛形を生成する
• ワークスペース固有またはカスタムのジェネレーターを実行する
• その他、nx ジェネレーターが存在するあらゆる作業

主要な原則

1. 常に --no-interactive を使用する - 実行を停止させてしまうプロンプトを防ぎます
2. ジェネレーターのソースコードを読む - スキーマだけでは不十分です。ジェネレーターが実際に何をするのかを理解してください
3. 既存のリポジトリのパターンに合わせる - リポジトリ内の類似した成果物を調査し、その規約に従ってください
4. lint/test/build/typecheck などで検証する - 生成されたコードは検証を通過する必要があります。記載されているターゲットはあくまで例であり、このワークスペースに適したものを使用してください。

手順

1. 利用可能なジェネレーターを確認する

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

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

これにはプラグインのジェネレーター（例: @nx/react:library）とローカルワークスペースのジェネレーターが含まれます。

2. ジェネレーターをユーザーのリクエストに合わせる

ユーザーのニーズを満たすことができるジェネレーターを特定します。どのような成果物の種類を求めているか、どのフレームワークが関連するか、言及されている特定のジェネレーター名があるかを考慮してください。

重要: ローカルワークスペースのジェネレーターと外部プラグインのジェネレーターの両方がリクエストを満たせる場合、常にローカルワークスペースのジェネレーターを優先してください。ローカルのジェネレーターは、特定のリポジトリのパターンに合わせてカスタマイズされています。

適切なジェネレーターが存在しない場合は、このスキルの使用を中止してかまいません。ただし、証明責任は高く、該当するものがないと判断する前に、利用可能なすべてのジェネレーターを慎重に検討してください。

3. ジェネレーターのオプションを取得する

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

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

必須オプション、上書きが必要になる可能性のあるデフォルト値、およびユーザーのリクエストに関連するオプションに注意してください。

ライブラリのビルド可否

ビルド可能にする特定の理由がない限り、デフォルトではビルド不可のライブラリにしてください。

種類	使用する場合	ジェネレーターのフラグ
ビルド不可（デフォルト）	アプリから消費される内部モノレポライブラリ	--bundler フラグなし
ビルド可能	npm への公開、リポジトリ間の共有、キャッシュヒットのための安定したライブラリ	--bundler=vite または --bundler=swc

ビルド不可のライブラリ:

• .ts/.tsx ソースを直接エクスポートする
• 消費側のバンドラーがそれらをコンパイルする
• 開発体験が高速で、設定が少ない

ビルド可能のライブラリ:

• 独自のビルドターゲットを持つ
• めったに変更されない安定したライブラリに有用（キャッシュヒット）
• npm 公開に必要

不明な場合は、ユーザーに尋ねてください: 「このライブラリはビルド可能（独自のビルドステップ、より良いキャッシュ）にすべきですか、それともビルド不可（ソースを直接消費、よりシンプルなセットアップ）にすべきですか?」

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

このステップは重要です。 スキーマだけではすべてを把握できません。ソースコードを読むことで、次のことが可能になります。

• どのファイルが作成/変更され、どこに配置されるかを正確に把握する
• 副作用 (設定の更新、依存関係のインストールなど) を理解する
• スキーマからは明らかでない動作やオプションを特定する
• オプション同士がどのように相互作用するかを理解する

ジェネレーターのソースコードを見つけるには:

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

ソースを読んだ後、再検討してください: これは適切なジェネレーターでしょうか？そうでない場合は、ステップ 2 に戻ってください。

⚠️ --directory フラグの動作は誤解を招く可能性があります。 これは、生成されるライブラリまたはコンポーネントの完全なパスを指定する必要があり、それが生成される親パスではありません。

# ✅ 正しい - directory はライブラリの完全なパス
nx g @nx/react:library --directory=libs/my-lib
# libs/my-lib/package.json などが生成されます

# ❌ 誤り - これは libs と libs/src/... にファイルを作成します
nx g @nx/react:library --name=my-lib --directory=libs
# libs/package.json などが生成されます

5. 既存のパターンを調べる

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

• 類似する既存の成果物 (他のライブラリ、アプリケーションなど) を確認する
• 命名規則、ファイル構造、設定パターンを特定する
• どのテストランナー、ビルドツール、リンターが使用されているかに注目する
• これらのパターンに合うようにジェネレーターを設定する

6. ドライランでファイルの配置を検証する

必ず最初に --dry-run を付けて実行し、ファイルが正しい場所に作成されることを検証してください:

npx nx g @nx/react:library --directory=libs/my-lib --dry-run --no-interactive

出力を注意深く確認してください。ファイルが誤った場所に作成される場合は、ジェネレーターのソースコードから得た知識に基づいてオプションを調整してください。

注: 一部のジェネレーターはドライランをサポートしていません (たとえば、npm パッケージをインストールする場合)。この理由でドライランが失敗した場合は、ジェネレーターを実際に実行する方へ進んでください。

7. ジェネレーターを実行する

ジェネレーターを実行します:

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

ヒント: 新しいパッケージでは、ワークスペースの依存関係を接続する必要があることがよくあります (たとえば、共有型のインポートや、アプリからの利用など)。link-workspace-packages スキルは、これらを正しく追加するのに役立ちます。

8. 生成されたコードを変更する (必要な場合)

ジェネレーターは出発点を提供します。必要に応じて出力を変更し、次のことを行います:

• 要求されたとおりに機能を追加または変更する
• インポート、エクスポート、または設定を調整する
• 既存のコードパターンと統合する

重要: 生成されたテストファイル (例: *.spec.ts) を置き換えたり削除したりする場合は、意味のある代替テストを書くか、プロジェクト設定から test ターゲットを削除してください。空のテストスイートは nx test を失敗させます。

9. フォーマットと検証

生成/変更されたすべてのファイルをフォーマットします:

nx format --fix

この例は、prettier を使用した組み込みの nx フォーマット用です。このワークスペースには他のフォーマットツールがある可能性があります。適切な場合はそれらを使用してください。

次に、生成されたコードが機能することを検証します。ジェネレーターで行った変更やその後の修正がさまざまなプロジェクトに影響を与える可能性があるため、通常は作成した成果物のターゲットだけを実行するだけでは十分ではないことに留意してください。

# these targets are just an example!
nx run-many -t build,lint,test,typecheck

これらのターゲットは、多くのワークスペースで使用される一般的な例です。このワークスペースとそのプロジェクトで利用可能な他のターゲットについても調査する必要があります。CI 設定は通常、合格しなければならない重要なターゲットを把握するための良い手がかりになります。

検証が対処可能な問題 (いくつかの lint エラー、軽微な型の問題) で失敗した場合は、それらを修正してください。問題が広範囲に及ぶ場合は、まず明らかな修正を試み、その後、何が生成され、何が失敗していて、何を試みたかの詳細を添えてユーザーにエスカレーションしてください。