TypeScriptプロジェクト

TypeScriptプロジェクトジェネレータは、ECMAScript Modules (ESM)、TypeScriptのプロジェクト参照、テスト実行用のVitest、リンティングとフォーマット用のBiomeなど、ベストプラクティスで構成されたモダンなTypeScriptライブラリまたはアプリケーションを作成するために使用できます。

使用方法

TypeScriptプロジェクトの生成

新しいTypeScriptプロジェクトを2つの方法で生成できます:

VSCode
CLI

インストール Nx Console VSCode Plugin まだインストールしていない場合
VSCodeでNxコンソールを開く
クリック Generate (UI) "Common Nx Commands"セクションで
検索 @aws/nx-plugin - ts#project
必須パラメータを入力
クリック Generate

pnpm nx g @aws/nx-plugin:ts#project

yarn nx g @aws/nx-plugin:ts#project

npx nx g @aws/nx-plugin:ts#project

bunx nx g @aws/nx-plugin:ts#project

変更されるファイルを確認するためにドライランを実行することもできます

pnpm nx g @aws/nx-plugin:ts#project --dry-run

yarn nx g @aws/nx-plugin:ts#project --dry-run

npx nx g @aws/nx-plugin:ts#project --dry-run

bunx nx g @aws/nx-plugin:ts#project --dry-run

オプション

パラメータ	型	デフォルト	説明
name 必須	string	-	TypeScriptプロジェクト名
directory	string	packages	ライブラリが配置される親ディレクトリ
subDirectory	string	-	ライブラリが配置されるサブディレクトリ。デフォルトではライブラリ名になります。
preferInstallDependencies	boolean	true	ジェネレーター実行後に依存関係のインストールを優先するかどうか。複数のジェネレーターをバッチ処理する際にインストールを延期する場合はfalseに設定します（後続のジェネレーターがNxプロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます）。最後に一度だけインストールします。

ジェネレータの出力

ジェネレータは<directory>/<name>ディレクトリに以下のプロジェクト構造を作成します:

Directorysrc TypeScriptソースコード
- index.ts
package.json プロジェクトのパッケージ名と依存関係を定義するプロジェクトマニフェスト
project.json プロジェクト設定とビルドターゲット
tsconfig.json このプロジェクトの基本TypeScript設定（ワークスペースルートのtsconfig.base.jsonを継承）
tsconfig.lib.json ライブラリ用TypeScript設定（ランタイムまたはパッケージ化ソース用）
tsconfig.spec.json テスト用TypeScript設定
vitest.config.mts Vitestの設定

ワークスペースルートの以下のファイルにも変更が加えられます:

nx.json Nx設定が更新され、@nx/js/typescriptプラグインがプロジェクト用に構成されます
tsconfig.base.json ワークスペース内の他のプロジェクトからインポート可能にするためのTypeScriptエイリアスが設定されます
tsconfig.json プロジェクト参照が追加されます

TypeScriptソースコードの記述

TypeScriptコードはsrcディレクトリに追加します。

ESMインポート構文

TypeScriptプロジェクトはESモジュールであるため、インポート文ではファイル拡張子を明示的に指定する必要があります:

import { sayHello } from './hello.js';

他のTypeScriptプロジェクト向けのエクスポート

TypeScriptプロジェクトのエントリポイントはsrc/index.tsです。他のプロジェクトからインポート可能にする要素はここでエクスポートできます:

export { sayHello } from './hello.js';
export * from './algorithms/index.js';

他のプロジェクトでのライブラリコードのインポート

ワークスペースのtsconfig.base.jsonで設定されたTypeScriptエイリアスを使用して、他のTypeScriptプロジェクトからプロジェクトを参照できます:

import { sayHello } from '@my-scope/my-library';

ワークスペース内の新しいプロジェクトを初めてインポートする場合、以下のようなエラーがIDEに表示される可能性があります:

インポートエラー

File '/path/to/my/workspace/packages/my-library/src/index.ts' is not under 'rootDir' '/path/to/my/workspace/packages/my-consumer'. 'rootDir' is expected to contain all source files.
  File is ECMAScript module because '/path/to/my/workspace/package.json' has field "type" with value "module" ts(6059)
File '/path/to/my/workspace/packages/my-library/src/index.ts' is not listed within the file list of project '/path/to/my/workspace/packages/my-consumer/tsconfig.lib.json'. Projects must list all files or use an 'include' pattern.
  File is ECMAScript module because '/path/to/my/workspace/package.json' has field "type" with value "module" ts(6307)

これはプロジェクト参照が設定されておらず、インポートされたプロジェクトがまだプロジェクトのpackage.jsonにワークスペース依存関係として宣言されていないためです。

ワークスペースは両方を管理する同期ジェネレータで構成されているため、手動で設定する必要はありません。以下のコマンドを実行するだけで、Nxが必要な設定を追加します:

pnpm nx sync

yarn nx sync

npx nx sync

bunx nx sync

 NX   The workspace is out of sync

[@nx/js:typescript-sync]: Some TypeScript configuration files are missing project references to the projects they depend on, contain stale project references, or have duplicate project references.
[@aws/nx-plugin:ts#sync]: Local project dependencies are out of sync. The following workspace dependencies will be declared:
packages/my-other-project/package.json:
- @my-scope/my-library: workspace:*

Syncing the workspace...
The workspace was synced successfully!

NxのTypeScript同期ジェネレータがプロジェクト参照を追加し、プラグインのts#syncジェネレータがインポートされたプロジェクトをプロジェクトのpackage.jsonに宣言します（パッケージマネージャがワークスペースプロトコルをサポートする場合はworkspace:*、npmとyarn classicでは*）。これにより、パッケージマネージャがインストール時にローカルプロジェクトをリンクします。この後、IDEのエラーが解消され、ライブラリを使用できるようになります。

プロジェクトをビルドするだけでも可能です — 同期ジェネレータが最初に実行され、未処理の変更を適用するよう促されます:

 NX   The workspace is out of sync

...

? Would you like to sync the identified changes to get your workspace up to date? …
Yes, sync the changes and run the tasks
No, run the tasks without syncing the changes

Yesを選択するとNxがワークスペースを同期します。

パスエイリアスの同期維持

プロジェクトのtsconfig.jsonにカスタムのcompilerOptions.pathsエントリを追加すると、TypeScriptはtsconfig.base.jsonで定義されたワークスペースエイリアスを継承しなくなります。隠れたts#syncジェネレータはcompileターゲットの前に実行され（nx.jsonで設定）、既にpathsを宣言しているtsconfig.json、tsconfig.lib.json、tsconfig.app.jsonファイルに不足している基本エイリアスをコピーします。オプトアウトするには、nx.jsonのtargetDefaults.compile.syncGeneratorsから@aws/nx-plugin:ts#syncを削除してください。

依存関係

各TypeScriptプロジェクトは、サードパーティのランタイム依存関係を独自のpackage.jsonで宣言します。プロジェクト間で共有されるビルドおよびテストツールは、ルートのpackage.jsonで定義されます。

プロジェクトにランタイム依存関係を追加するには、そのプロジェクトにインストールします:

pnpm add some-npm-package --filter my-library

yarn workspace @my-scope/my-library add some-npm-package

npm install --legacy-peer-deps some-npm-package -w packages/my-library

bun add some-npm-package --cwd packages/my-library

プロジェクトのディレクトリ内からパッケージマネージャの通常のadd/installコマンドを実行することもできます。

共有開発ツールを追加するには、ワークスペースルートにインストールします:

pnpm add -Dw some-dev-tool

yarn add -D some-dev-tool

npm install --legacy-peer-deps -D some-dev-tool

bun add -D some-dev-tool

カタログ

カタログをサポートするパッケージマネージャ（pnpm、yarn、bun）の場合、ジェネレータは各バージョンをカタログに記録し、catalog:プロトコル（例："zod": "catalog:"）で参照します。これにより、どのプロジェクトが依存関係を宣言しているかに関係なく、カタログがバージョンの唯一の信頼できる情報源となります。これは単一バージョンポリシーに従うのに役立ち、型の競合やデプロイメントバンドル内のパッケージの複数コピーを回避できます。

新しい依存関係を自分で追加する場合も、カタログに保持してください:

ワークスペースはcatalogMode: strictを設定しているため、pnpm addがバージョンをカタログに記録し、自動的に参照します — 追加の手順は不要です。

pnpm add some-npm-package --filter my-library

yarnのcatalog:プロトコルは既存のカタログエントリを参照するだけで、新しいエントリを作成できません — まずバージョンを記録してください。

.yarnrc.ymlのcatalogにバージョンを追加します:
.yarnrc.yml
```
catalog:
  some-npm-package: ^1.0.0
```

プロジェクトから参照します:

yarn workspace @my-scope/my-library add some-npm-package@catalog:

bunのcatalog:プロトコルは既存のカタログエントリを参照するだけで、新しいエントリを作成できません — まずバージョンを記録してください。

ルートのpackage.jsonのcatalogにバージョンを追加します:
package.json
```
{
  "catalog": {
    "some-npm-package": "^1.0.0"
  }
}
```

プロジェクトから参照します:

bun add some-npm-package@catalog: --cwd packages/my-library

カタログのオプトアウト

カタログはデフォルトで有効になっています。無効にするには、--catalog falseを指定してワークスペースを作成します:

pnpm create @aws/nx-workspace my-project --catalog false

yarn create @aws/nx-workspace my-project --catalog false

npm create @aws/nx-workspace -- my-project --catalog false

bun create @aws/nx-workspace my-project --catalog false

または、いつでもaws-nx-plugin.config.mtsで設定できます:

export default {
  packageManager: {
    catalogs: false,
  },
} satisfies AwsNxPluginConfig;

カタログを無効にすると、ジェネレータは依存関係のバージョンを各プロジェクトのpackage.jsonに直接書き込み、プロジェクト間でバージョンを揃えることはあなたの責任になります。

すべての依存関係をルートで宣言する

すべての依存関係をルートのpackage.jsonのみで宣言することを好む場合（プロジェクトごとの依存関係宣言なし）、ワークスペースのbiome.jsonでリントルールをオフにします:

{
  "linter": {
    "rules": {
      "correctness": {
        "noUndeclaredDependencies": "off"
      }
    }
  }
}

プロジェクトはビルド時にルートにインストールされたパッケージを解決するため、すべてが正常にビルドされます — ただし、各プロジェクトの依存関係の正確な記録としてのプロジェクトごとのマニフェストを放棄することになります（これは後でプロジェクトを公開したり、リポジトリを分割したりする場合に重要です）。

ランタイムコード

TypeScriptプロジェクトをランタイムコード（例：AWS Lambda関数のハンドラ）として使用する場合、Rolldownなどのツールを使用してプロジェクトをバンドルすることを推奨します。これにより、実際に参照されている依存関係のみが含まれるようツリーシェイキングされます。

project.jsonファイルに以下のようなターゲットを追加することで実現できます:

{
  ...
  "targets": {
    ...
    "bundle": {
      "cache": true,
      "executor": "nx:run-commands",
      "outputs": ["{workspaceRoot}/dist/packages/my-library/bundle"],
      "options": {
        "command": "rolldown -c rolldown.config.ts"
      }
    },
  },
}

rolldown.config.tsファイルは以下のように追加します:

import { defineConfig } from 'rolldown';

export default defineConfig([
  {
    input: 'src/index.ts',
    output: {
      file: '../../dist/packages/my-library/bundle/index.js',
      format: 'cjs',
      inlineDynamicImports: true,
    },
  },
]);

ビルド

TypeScriptプロジェクトにはbuildターゲット（project.jsonで定義）が設定されており、以下のコマンドで実行できます:

pnpm nx build <project-name>

yarn nx build <project-name>

npx nx build <project-name>

bunx nx build <project-name>

<project-name>はプロジェクトの完全修飾名です。

buildターゲットはプロジェクトのコンパイル、リンティング、テストを実行します。

ビルド出力はワークスペースルートのdistフォルダ内のパッケージディレクトリ（例: dist/packages/<my-library>/tsc）に生成されます。

ワークスペース内のすべてのプロジェクトをビルドするには、以下を実行します:

pnpm nx run-many --target build

yarn nx run-many --target build

npx nx run-many --target build

bunx nx run-many --target build

または、ショートハンドコマンドを使用します:

pnpm build

yarn build

npm run build

bun build

テスト

Vitestがプロジェクトのテスト用に設定されています。

テストの記述

テストは.spec.tsまたは.test.tsファイルに記述し、プロジェクトのsrcフォルダに配置します。

例:

Directorysrc
- hello.ts ライブラリソースコード
- hello.spec.ts hello.tsのテスト

Vitestはdescribe、it、test、expectなどのJest風の構文を提供します。

import { sayHello } from './hello.js';

describe('sayHello', () => {

  it('should greet the caller', () => {
    expect(sayHello('Darth Vader')).toBe('Hello, Darth Vader!');
  });

});

テストの記述方法や依存関係のモック作成などの詳細については、Vitestドキュメントを参照してください。

テストの実行

テストはプロジェクトのbuildターゲットの一部として実行されますが、testターゲットを個別に実行することもできます:

pnpm nx test <project-name>

yarn nx test <project-name>

npx nx test <project-name>

bunx nx test <project-name>

Vitestの-tフラグを使用して特定のテストまたはテストスイートを実行できます。--セパレータの後に渡すことで、Nxが独自の--targetオプションとして解釈するのではなく、Vitestに転送されます:

pnpm nx test <project-name> -- -t 'sayHello'

yarn nx test <project-name> -- -t 'sayHello'

npx nx test <project-name> -- -t 'sayHello'

bunx nx test <project-name> -- -t 'sayHello'

リンティング

TypeScriptプロジェクトでは、リンティングとフォーマットにBiomeを使用します。Biomeはワークスペースルートのbiome.jsonファイルで設定されます。この設定への変更はワークスペース内のすべてのTypeScriptプロジェクトに適用され、一貫性が保たれます。

リンターの実行

プロジェクトのリンターをチェックするにはlintターゲットを実行します:

pnpm nx lint <project-name>

yarn nx lint <project-name>

npx nx lint <project-name>

bunx nx lint <project-name>

リント問題の修正

ほとんどのリンティングやフォーマットの問題は、--configuration=fix引数を付けて実行することで自動修正できます:

pnpm nx lint <project-name> --configuration=fix

yarn nx lint <project-name> --configuration=fix

npx nx lint <project-name> --configuration=fix

bunx nx lint <project-name> --configuration=fix

ワークスペース内のすべてのパッケージのリント問題を修正するには:

pnpm nx run-many --target lint --all --configuration=fix

yarn nx run-many --target lint --all --configuration=fix

npx nx run-many --target lint --all --configuration=fix

bunx nx run-many --target lint --all --configuration=fix

ワークスペースルートからのショートハンドコマンドがあります:

pnpm lint

yarn lint

npm run lint

bun lint

リント問題のスキップ

開発中にリンティング問題で作業が遅くなるのを避けるため（特にプロジェクトに自動修正できない問題がある場合）、skip-lint設定でビルドを実行できます:

pnpm nx run-many --target build --configuration=skip-lint

yarn nx run-many --target build --configuration=skip-lint

npx nx run-many --target build --configuration=skip-lint

bunx nx run-many --target build --configuration=skip-lint

これによりビルド中にlintターゲットが完全にスキップされます。

ワークスペースルートからのショートハンドコマンドがあります:

pnpm build:skip-lint

yarn build:skip-lint

npm run build:skip-lint

bun build:skip-lint