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

TypeScriptソースコードの記述

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

ESMインポート構文

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

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)

これはプロジェクト参照が設定されていないためです。

TypeScriptプロジェクトはNx TypeScript Syncジェネレータで事前設定されているため、手動での設定は不要です。以下のコマンドを実行するとNxが必要な設定を追加します:

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モノレポに慣れている場合、予期しないことでしょう。

モノレポ内の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関数のハンドラ）として使用する場合、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ファイルは以下のように追加します:

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,
    },
  },
]);

Note

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

Tip

AWS Lambda関数を構築する場合は、ts#lambda-functionジェネレータを確認してください。バンドリングの設定に加え、インフラストラクチャの生成、可観測性、型安全性の追加が行われます。

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拡張機能のインストールをお勧めします。IDEからテストの実行、監視、デバッグが可能になります。

リンティング

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

ワークスペースルートのeslint.config.mjsファイルでESLintを構成することを推奨します。これにより、変更がワークスペース内のすべての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引数を付けてESLintを実行することで修正できます:

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