TypeScriptプロジェクト

TypeScriptプロジェクトジェネレータは、ECMAScript Modules (ESM)、TypeScript プロジェクトリファレンス、テスト実行用のVitest、静的解析用のESLintなど、ベストプラクティスで構成されたモダンなTypeScriptライブラリやアプリケーションの作成に使用できます。

使用方法

TypeScriptプロジェクトの生成

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

VSCode

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

オプション

パラメータ	型	デフォルト	説明
name 必須	string	-	TypeScript project name
directory	string	packages	Parent directory where the library is placed.
subDirectory	string	-	The sub directory the lib is placed in. By default this is the library name.

ジェネレータの出力

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

• Directorysrc TypeScriptソースコード

  • index.ts
• project.json プロジェクト設定とビルドターゲット
• tsconfig.json プロジェクトの基本TypeScript設定（ワークスペースルートのtsconfig.base.jsonを継承）
• tsconfig.lib.json ライブラリ用TypeScript設定（ランタイムまたはパッケージ化ソース）
• tsconfig.spec.json テスト用TypeScript設定
• vite.config.ts Vitest設定
• eslint.config.mjs ESLint設定

Tip

package.jsonファイルが作成されていないことに注目してください！理由は後述で説明します。

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

• nx.json @nx/js/typescriptプラグインの設定が更新されます
• tsconfig.base.json ワークスペース内の他プロジェクトからインポート可能にするTypeScriptエイリアスが設定されます
• tsconfig.json プロジェクトリファレンスが追加されます

TypeScriptソースコードの作成

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

ESMインポート構文

TypeScriptプロジェクトはESモジュールであるため、ファイル拡張子を明示的に指定した正しいESM構文でインポート文を作成してください：

index.ts

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

Note

TypeScriptを使用していても、sayHelloがhello.tsで定義されている場合、インポートでは.jsファイル拡張子を使用します。詳細はこちらで確認できます。

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

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

src/index.ts

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

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

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

packages/my-other-project/src/index.ts

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

Note

TypeScriptプロジェクトのエイリアスは従来の@ではなく:で始まります。これにより、ワークスペース内のローカルパッケージとNPMのリモートパッケージ間での名前衝突を防ぎます。

ワークスペース内の新しいプロジェクトを初めてインポートする場合、以下のような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)

これはプロジェクトリファレンスが設定されていないためです。

Nx TypeScript Syncジェネレータが自動的に設定を行うため、手動での設定は不要です。以下のコマンドを実行してください：

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

これによりIDEエラーが解消され、ライブラリを使用できるようになります。

Tip

プロジェクトをビルドする際、以下のようなメッセージが表示される場合もあります：

[@nx/js:typescript-sync]: Some TypeScript configuration files are missing project references to the projects they depend on or contain outdated project references.

This will result in an error in CI.

? 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がプロジェクトリファレンスを更新します。

依存関係

TypeScriptプロジェクトにpackage.jsonファイルが存在しない点に驚かれるかもしれません。これは従来のTypeScriptモノレポとは異なる仕様です。

依存関係を追加するには、ワークスペースルートのpackage.jsonに追加します。パッケージマネージャのコマンドラインを使用できます：

pnpm

pnpm add -w some-npm-package

yarn

yarn add some-npm-package

npm

npm install --legacy-peer-deps some-npm-package

bun

bun install some-npm-package

これにより、ワークスペース内の全TypeScriptプロジェクトで依存関係が利用可能になります。

ランタイムコード

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

project.jsonファイルに以下のようなターゲットを追加できます：

{
  ...
  "targets": {
    ...
    "bundle": {
      "cache": true,
      "executor": "nx:run-commands",
      "outputs": ["{workspaceRoot}/dist/packages/my-library/bundle"],
      "options": {
        "command": "esbuild packages/my-library/src/index.ts --bundle --outfile=dist/packages/my-library/bundle/index.js --platform=node --format=cjs"
      }
    },
  },
}

Note

上記のターゲットではsrc/index.tsをバンドルのエントリポイントとして指定しています。このファイルからエクスポートされたコードとその依存関係がバンドルに含まれます。

NPMへの公開

TypeScriptプロジェクトをNPMに公開する場合は、package.jsonファイルを作成する必要があります。

このファイルにはプロジェクトが参照する依存関係を宣言する必要があります。ビルド時にワークスペースルートのpackage.jsonから依存関係が解決されるため、Nx Dependency Checks ESLint Pluginを設定し、公開用package.jsonに必要な依存関係がすべて含まれるようにすることを推奨します。

ビルド

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

pnpm

pnpm nx run <project-name>:build

yarn

yarn nx run <project-name>:build

npm

npx nx run <project-name>:build

bun

bunx nx run <project-name>:build

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

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

ビルド出力はワークスペースルートのdistフォルダ内（例：dist/packages/<my-library>/tsc）に生成されます。

テスト

Vitestがテスト実行用に設定されています。

テストの作成

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

例：

• Directorysrc

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

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

hello.spec.ts

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

describe('sayHello', () => {

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

});

テストの作成方法やモック機能などの詳細はVitestドキュメントを参照してください。

テストの実行

テストはbuildターゲットの一部として実行されますが、testターゲットで個別に実行することも可能です：

pnpm

pnpm nx run <project-name>:test

yarn

yarn nx run <project-name>:test

npm

npx nx run <project-name>:test

bun

bunx nx run <project-name>:test

-tフラグを使用して特定のテストを実行できます：

pnpm

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

yarn

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

npm

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

bun

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

Tip

VSCodeユーザーには、テストの実行・監視・デバッグが可能なVitest Runner for VSCode that actually works拡張機能のインストールを推奨します。

リンティング

TypeScriptプロジェクトではリンティングにESLint、フォーマットにPrettierを使用します。

ESLintの設定はワークスペースルートのeslint.config.mjsファイルで行うことを推奨します。これによりワークスペース内の全TypeScriptプロジェクトに設定が適用され、一貫性が保たれます。

Prettierの設定もルートの.prettierrcファイルで行えます。

リンターの実行

プロジェクトのリンティングチェックはlintターゲットで実行できます：

pnpm

pnpm nx run <project-name>:lint

yarn

yarn nx run <project-name>:lint

npm

npx nx run <project-name>:lint

bun

bunx nx run <project-name>:lint

リント問題の修正

ほとんどのリンティングやフォーマットの問題は自動修正可能です。--configuration=fix引数を付けて実行します：

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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