Skip to content
@aws/nx-plugin
Blog

TypeScriptプロジェクト

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

使用方法

TypeScriptプロジェクトの生成

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

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

    オプション

    パラメータ 型 デフォルト 説明
    name 必須 string - Library 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の設定

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

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

    TypeScriptソースコードの記述

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

    ESMインポート構文

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

    index.ts
    import { sayHello } from './hello.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';

    ワークスペースで新しいプロジェクトのインポート文を初めて追加する際、以下のようなエラーがIDEに表示される場合があります：

    インポートエラー
    Terminal window
    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ジェネレータがデフォルトで構成されているため、手動での設定は不要です。以下のコマンドを実行すると必要な構成が追加されます：

    Terminal window
    pnpm nx sync

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

    依存関係

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

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

    Terminal window
    pnpm add -w 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"
          }
        },
      },
    }

    NPMへの公開

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

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

    ビルド

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

    Terminal window
    pnpm 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ターゲットを個別に実行することもできます：

    Terminal window
    pnpm nx run <project-name>:test

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

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

    リンティング

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

    ワークスペースルートのeslint.config.mjsファイルでESLintを構成することを推奨します。これにより変更がすべてのTypeScriptプロジェクトに適用され、一貫性が保たれます。

    同様に、Prettierはルートの.prettierrcファイルで構成できます。

    リンターの実行

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

    Terminal window
    pnpm nx run <project-name>:lint

    リント問題の修正

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

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

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

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