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 - 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設定

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

    • 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';

    他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モノレポとは異なる仕様です。

    依存関係を追加するには、ワークスペースルートの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の設定はワークスペースルートのeslint.config.mjsファイルで行うことを推奨します。これによりワークスペース内の全TypeScriptプロジェクトに設定が適用され、一貫性が保たれます。

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

    リンターの実行

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

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

    リント問題の修正

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

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

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

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