TypeScript の使用の開始プロジェクトの作成ローカルの tsc および cdk の使用 AWS コンストラクトライブラリモジュールの管理 TypeScript の依存関係の管理 TypeScript の AWS CDK イディオム CDK アプリの構築と実行

TypeScript で AWS CDK を使用する

TypeScript は AWS Cloud Development Kit (AWS CDK) で完全にサポートされているクライアント言語であり、安定していると考えられています。TypeScript で AWS CDK を使用すると、Microsoft の TypeScript コンパイラ (tsc)、Node.js、Node Package Manager (npm) などの使い慣れたツールを利用できます。このガイドの例では NPM を使用していますが、必要に応じて Yarn を使用することもできます。AWS コンストラクトライブラリを構成するモジュールは、NPM リポジトリの npmjs.org を介して配布されます。

任意のエディタまたは IDE を使用できます。多くの AWS CDK デベロッパーは Visual Studio Code (または同等のオープンソースの VSCodium) を使用しており、TypeScript のサポートが良好です。

TypeScript の使用の開始

AWS CDK を使用するには、AWS アカウントおよび認証情報を持ち、Node.js および AWS CDK Toolkit がインストールされている必要があります。「AWS CDK の使用を開始する」を参照してください。

TypeScript 自体 (バージョン 3.8 以降) も必要です。まだインストールしていない場合、npm を使用してインストールできます。


$ npm install -g typescript

注記

アクセス許可エラーが発生し、システムで管理者アクセス権がある場合、sudo npm install -g typescript を試してください。

TypeScript を通常の npm update -g typescript で最新の状態に保ちます。

注記

サードパーティー言語の廃止: 言語バージョンは、ベンダーまたはコミュニティによって共有される EOL (製品終了) までのみサポートされ、事前の通知によって変更されます。

プロジェクトの作成

空のディレクトリで cdk init を呼び出すことにより、新しい AWS CDK プロジェクトを作成します。--language オプションを使用して typescript を指定します。


$ mkdir my-project
$ cd my-project
$ cdk init app --language typescript

プロジェクトを作成すると、aws-cdk-lib モジュールおよびその依存関係もインストールされます。

cdk init はプロジェクトフォルダの名前を使用し、クラス、サブフォルダ、ファイルなどのプロジェクトのさまざまな要素に名前を付けます。フォルダ名に含まれるハイフンはアンダースコアに変換されます。ただし、それ以外の場合、名前は TypeScript 識別子の形式に従う必要があります。例えば、数字で始まったり、スペースを含めたりすることはできません。

ローカルの `tsc` および `cdk` の使用

ほとんどの場合、このガイドは TypeScript および CDK Toolkit をグローバルにインストールすることを前提としており (npm install -g typescript aws-cdk)、提供されたコマンドの例 (cdk synth など) はこの前提に従います。このアプローチによって両方のコンポーネントを最新の状態に保つことが容易になり、両方とも下位互換性に厳格なアプローチを取っているため、常に最新バージョンを使用するリスクは一般的にほとんどありません。

TypeScript コンパイラや CDK Toolkit などのツールを含め、一部のチームは各プロジェクト内のすべての依存関係を指定することを好みます。この実践は、これらのコンポーネントを特定のバージョンに固定し、チームのすべてのデベロッパー (および CI/CD 環境) がそれらのバージョンのみを使用できるようにします。変更になりうる原因がなくなり、ビルドおよびデプロイの一貫性および再現性が向上します。

CDK には TypeScript プロジェクトテンプレートの package.json に TypeScript および CDK Toolkit の両方の依存関係が含まれているため、このアプローチを使用する場合、プロジェクトを変更する必要はありません。アプリの構築および cdk コマンドの発行には若干異なるコマンドを使用することのみが必要です。

Operation	グローバルツールの使用	ローカルツールの使用
プロジェクトの初期化	`cdk init --language typescript`	`npx aws-cdk init --language typescript`
ビルド	`tsc`	`npm run build`
CDK Toolkit コマンドの実行	`cdk …`	`npm run cdk …`-または-`npx aws-cdk …`

現在のプロジェクトにローカルにインストールされている CDK Toolkit のバージョンが存在する場合、npx aws-cdk はそれを実行します。グローバルインストールがある場合、それにフォールバックします。グローバルインストールが存在しない場合、npx は CDK Toolkit の一時コピーをダウンロードしてそれを実行します。@ 構文を使用して CDK Toolkit の任意のバージョンを指定できます。npx aws-cdk@2.0 --version は 2.0.0 を出力します。

ヒント

ローカル CDK Toolkit のインストールで cdk コマンドを使用できるように、エイリアスを設定します。

AWS コンストラクトライブラリモジュールの管理

ノードパッケージマネージャー (npm) を使用し、アプリが使用する AWS コンストラクトライブラリモジュールに加え、必要なその他のパッケージをインストールおよび更新します。(必要に応じて npm ではなく、yarn を使用できます) npm は、それらのモジュールの依存関係も自動的にインストールします。

ほとんどの AWS CDK コンストラクトは、aws-cdk-lib という名前のメイン CDK パッケージにあります。これは cdk init によって作成された新しいプロジェクトにおけるデフォルトの依存関係です。「実験的」な AWS コンストラクトライブラリモジュールは、上位レベルのコンストラクトがまだ開発中であり、@aws-cdk/<SERVICE-NAME>-alpha のように名前が付けられます。サービス名には aws- のプレフィックスがあります。モジュールの名前が不明な場合、NPM で検索します。

注記

CDK API リファレンスには、パッケージ名も表示されます。

例えば、以下のコマンドは AWS CodeStar の実験モジュールをインストールします。


$ npm install @aws-cdk/aws-codestar-alpha

一部のサービスのコンストラクトライブラリサポートは、複数の名前空間にあります。例えば、aws-route53 の他にも追加の Amazon Route 53 名前空間が 3 つのあり、それぞれ aws-route53-targets、aws-route53-patterns、aws-route53resolver です。

プロジェクトの依存関係は package.json で維持されます。このファイルを編集して依存関係の一部またはすべてを特定のバージョンにロックするか、特定の条件で新しいバージョンに更新することができます。package.json で指定したルールに従って、プロジェクトの NPM 依存関係を最新の許可されたバージョンに更新する方法


$ npm update

TypeScript では、NPM を使用してモジュールをインストールするために使用するときと同じ名前で、モジュールをコードにインポートします。クラス AWS CDK および AWS コンストラクトライブラリモジュールをアプリケーションにインポートするとき、次の内容を実践することをお勧めします。これらのガイドラインに従うと、コードが他の AWS CDK アプリケーションと一貫性を持ち、わかりやすくなります。

require() ではなく、ES6 形式の import ディレクティブを使用します。
一般的に、aws-cdk-lib から個々のクラスをインポートします。
```
import { App, Stack } from 'aws-cdk-lib';
```
aws-cdk-lib から多くのクラスが必要な場合、個々のクラスをインポートするのではなく、cdk の名前空間エイリアスを使用できます。両方を実行しないでください。
```
import * as cdk from 'aws-cdk-lib';
```
一般的に、短い名前空間エイリアスを使用して AWS サービスコンストラクトをインポートします。
```
import { aws_s3 as s3 } from 'aws-cdk-lib';
```

TypeScript の依存関係の管理

TypeScript CDK プロジェクトでは、依存関係はプロジェクトのメインディレクトリの package.json ファイルで指定されます。コア AWS CDK モジュールは、aws-cdk-lib という 1 つの NPM パッケージにあります。

npm install を使用してパッケージをインストールすると、NPM はパッケージを package.json に記録します。

必要に応じて、NPM の代わりに Yarn を使用できます。ただし、CDK は Yarn のプラグアンドプレイモードをサポートしていません。このモードは、Yarn 2 のデフォルトモードです。プロジェクトの .yarnrc.yml ファイルに次のものを追加し、この機能をオフにします。


nodeLinker: node-modules

CDK アプリケーション

次の例は、cdk init --language typescript コマンドで生成された package.json ファイルです。


{
  "name": "my-package",
  "version": "0.1.0",
  "bin": {
    "my-package": "bin/my-package.js"
  },
  "scripts": {
    "build": "tsc",
    "watch": "tsc -w",
    "test": "jest",
    "cdk": "cdk"
  },
  "devDependencies": {
    "@types/jest": "^26.0.10",
    "@types/node": "10.17.27",
    "jest": "^26.4.2",
    "ts-jest": "^26.2.0",
    "aws-cdk": "2.16.0",
    "ts-node": "^9.0.0",
    "typescript": "~3.9.7"
  },
  "dependencies": {
    "aws-cdk-lib": "2.16.0",
    "constructs": "^10.0.0",
    "source-map-support": "^0.5.16"
  }
}

デプロイ可能な CDK アプリケーションの場合、package.json の dependencies セクションで aws-cdk-lib を指定する必要があります。同じメジャーバージョン内にある限り、キャレット (^) バージョン番号の指定子を使用し、指定されたバージョンよりも新しいバージョンを受け入れることを示すことができます。

実験的なコンストラクトの場合、変更される可能性のある API を持つアルファコンストラクトライブラリモジュールの正確なバージョンを指定します。これらのモジュールの新しいバージョンには、アプリが破損する恐れのある API 変更が発生する可能性があるため、^ または ~ を使用しないでください。

package.json の devDependencies セクションで、アプリをテストするために必要なライブラリおよびツールのバージョン (例えば、jest テストフレームワークなど) を指定します。オプションとして、^ を使用して新しい互換性のあるバージョンが許容されることを指定します。

サードパーティーのコンストラクトライブラリ

コンストラクトライブラリを開発している場合、次の package.json ファイル例で示すように、peerDependencies セクションと devDependencies セクションの組み合わせを使用して依存関係を指定します。


{
  "name": "my-package",
  "version": "0.0.1",
  "peerDependencies": {
    "aws-cdk-lib": "^2.14.0",
    "@aws-cdk/aws-appsync-alpha": "2.10.0-alpha",
    "constructs": "^10.0.0"
  },
  "devDependencies": {
    "aws-cdk-lib": "2.14.0",
    "@aws-cdk/aws-appsync-alpha": "2.10.0-alpha",
    "constructs": "10.0.0",
    "jsii": "^1.50.0",
    "aws-cdk": "^2.14.0"
  }
}

peerDependencies でキャレット (^) を使用してライブラリが使用する aws-cdk-lib の最低バージョンを指定します。ライブラリとさまざまな CDK バージョンとの互換性が最大化されます。変更される可能性のある API を持つアルファコンストラクトライブラリモジュールの正確なバージョンを指定します。peerDependencies を使用することで、node_modules ツリーですべての CDK ライブラリのコピーが 1 つしか存在しないことが保証されます。

テストに必要なツールおよびライブラリを devDependencies で指定します。オプションとして ^ を含めて指定し、新しい互換性のあるバージョンが許容可能であることを示します。ライブラリが aws-cdk-lib およびその他の CDK パッケージと互換性があることをアドバタイズする最低バージョンを正確に (^ または ~ なしで) 指定します。これを実践すると、テストがこれらのバージョンに対して実行されていることを確認できます。これにより、新しいバージョンでのみ見つかった機能を誤って使用した場合、テストで検出できます。

警告

peerDependencies は NPM 7 以降でのみ自動的にインストールされます。NPM 6 以前または Yarn を使用している場合、依存関係の依存関係を devDependencies に含める必要があります。そうしないと、インストールされないため、未解決のピア依存関係に関する警告が表示されます。

依存関係のインストールと更新

次のコマンドを実行してプロジェクトの依存関係をインストールします。

インストールされたモジュールを更新するには、前述の npm install コマンドと yarn upgrade コマンドを使用できます。いずれのコマンドも、package.json のルールを満たす最新バージョンに node_modules のパッケージを更新します。ただし、package.json 自体は更新されません。新しい最小バージョンを設定するために行うことができます。GitHub でパッケージをホストする場合、package.json を自動的に更新するように Dependabot バージョンの更新プログラムを設定できます。または、npm-check-updates を使用します。

重要

設計上、依存関係をインストールまたは更新するとき、NPM および Yarn は package.json で指定された要件を満たすすべてのパッケージの最新バージョンを選択します。これらのバージョンが (誤ってまたは意図的に) 破損するリスクが常にあります。プロジェクトの依存関係を更新した後は、徹底的なテストを行ってください。

TypeScript の AWS CDK イディオム

Props

すべての AWS コンストラクトライブラリクラスは、3 つの引数を使用してインスタンス化されます。コンストラクトが定義されているscope (コンストラクトツリー内の親)、ID、props があります。引数のpropsは、コンストラクトが作成する AWS リソースの設定に使用するキーと値のペアのバンドルです。他のクラスやメソッドでは、引数に「属性のバンドル」パターンも使用されます。

TypeScript では、必要な引数およびオプションの引数に加え、それぞれのタイプを指定するインターフェイスを使用して props の形状が定義されます。このようなインターフェイスは props 引数の種類ごとに定義され、通常は単一のコンストラクトまたはメソッドの固有なものです。例えば、Bucket コンストラクト (aws-cdk-lib/aws-s3 モジュール内) は、BucketProps インターフェイスに適合する props 引数を指定します。

プロパティ自体がオブジェクトの場合 (例えば、BucketProps の websiteRedirect プロパティなど)、そのオブジェクトには独自のインターフェイスがあり、その形状が適合する必要があります。この場合は RedirectTarget です。

AWS コンストラクトライブラリクラスをサブクラス化する場合 (または props のような引数を取るメソッドを上書きする場合)、既存のインターフェイスから継承して、コードに必要な新しい props を指定する新しいインターフェイスを作成できます。親クラスまたはベースメソッドを呼び出すとき、オブジェクトで指定されても、インターフェイスで指定されていない属性は無視されるため、一般的に受け取った props 引数全体を渡すことができます。

AWS CDK の将来のリリースでは、お持ちのプロパティに使用した名前を持つ新しいプロパティが同時に追加される可能性があります。受け取る値を継承チェーンの上方に渡すと、予期しない動作が発生する可能性があります。プロパティを削除または undefined に設定した状態で受け取った props の浅いコピーを渡す方が安全です。例:


super(scope, name, {...props, encryptionKeys: undefined});

または、プロパティに名前を付けてコンストラクトに属していることを明確にします。今後の AWS CDK リリースでプロパティと衝突する可能性は低くなります。多数ある場合、適切に名前が付けられたオブジェクトを 1 つ使用して保持します。

欠落した値

オブジェクト (props など) の欠落値は TypeScript で undefined の値になります。言語のバージョン 3.7 では、これらの値の使用を簡素化する演算子が導入され、未定義の値に達したときにデフォルトおよび「短絡」連鎖を指定しやすくなります。これらの機能の詳細については、「TypeScript 3.7 リリースノート」を参照し、特に最初の 2 つの機能である「オプションの連鎖」および「NULL 合体」をお読みください。

CDK アプリの構築と実行

一般的に、アプリケーションを構築して実行するとき、プロジェクトのルートディレクトリにいる必要があります。

Node.js は TypeScript を直接実行することはできません。代わりに、アプリケーションは TypeScript コンパイラの tsc を使用して JavaScript に変換されます。その後、結果の JavaScript コードが実行されます。

アプリを実行する必要があるたびに、AWS CDK はこれを自動的に行います。ただし、エラーをチェックしてテストを実行するため、手動でコンパイルすると便利です。TypeScript アプリを手動でコンパイルするには、npm run build を発行します。視聴モードに入るために npm run watch を発行することもあり、ソースファイルに変更を保存するたびに TypeScript コンパイラが自動的にアプリを再構築します。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

CDK ライブラリの使用

JavaScript の場合