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

AWS CDK でのの操作 TypeScript

TypeScript はで完全にサポートされているクライアント言語であり AWS Cloud Development Kit (AWS CDK) 、安定していると見なされます。 AWS CDK でを操作すると、Microsoft のコン TypeScript パイラ (tsc）、Node.js、Node Package Manager () など、使い慣れたツール TypeScript が使用されますnpm。このガイドの例ではを使用していますが、必要に応じて Yarn を使用することもできますNPM。コンストラクトライブラリを構成するモジュールは、NPMリポジトリ AWS 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 、プロジェクトテンプレートのに TypeScript と CDK Toolkit の両方の依存関係が含まれているためpackage.json、このアプローチを使用する場合は、プロジェクトを変更する必要はありません。必要なのは、アプリケーションの構築とコマンドの発行に少し異なるcdkコマンドを使用することだけです。

操作	グローバルツールを使用する	ローカルツールを使用する
プロジェクトの初期化	`cdk init --language typescript`	`npx aws-cdk init --language typescript`
ビルド	`tsc`	`npm run build`
CDK ツールキットの実行コマンド	`cdk ...`	`npm run cdk ...`、または `npx aws-cdk ...`

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

ヒント

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

AWS 構築ライブラリモジュールの管理

Node Package Manager (npm) を使用して、アプリケーションで使用する AWS 構築ライブラリモジュール、および必要なその他のパッケージをインストールおよび更新します。（npm必要に応じて yarnの代わりにを使用できます。) は、それらのモジュールの依存関係npmも自動的にインストールします。

ほとんどの AWS CDK コンストラクトは、という名前のメインCDKパッケージにあります。これはaws-cdk-lib、によって作成された新しいプロジェクトのデフォルトの依存関係です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 名前空間、aws-route53-targets、aws-route53-patternsおよびが 3 つ追加されていますaws-route53resolver。

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


npm update

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

ではなく、 ES6スタイルのimportディレクティブを使用しますrequire()。
通常、から個々のクラスをインポートします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 モジュールは、という 1 つのNPMパッケージにありますaws-cdk-lib。

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

必要に応じて、の代わりに Yarn を使用できますNPM。ただし、 CDKは Yarn の plug-and-play モードをサポートしていません。これは 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アプリケーションの場合、の dependenciesセクションでを指定aws-cdk-libする必要がありますpackage.json。キャレット (^) バージョン番号指定子を使用して、同じメジャーバージョン内にある限り、指定したバージョンよりも新しいバージョンを受け入れるように指定できます。

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

の devDependenciesセクションで、アプリケーションのテストに必要なライブラリとツールのバージョン (jestテストフレームワークなど) を指定しますpackage.json。オプションで、^ を使用して、それ以降の互換性のあるバージョンが許容可能であることを指定します。

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

コンストラクトライブラリを開発している場合は、次のサンプル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バージョンとの互換性が最大化されます。アルファコンストラクトライブラリモジュールには、変更されるAPIs可能性のある正確なバージョンを指定します。peerDependencies を使用すると、ツリー内のすべてのCDKライブラリのコピーが 1 node_modules つだけになります。

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

警告

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

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

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

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

重要

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

AWS CDK のイディオム TypeScript

プロンプト

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

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

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

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

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


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

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

欠落した値

オブジェクトの欠損値 (props など) は、 undefinedの値を持ちます TypeScript。言語のバージョン 3.7 では、これらの値の操作を簡素化する演算子が導入されました。これにより、未定義の値に達したときにデフォルトと「ショート」チェーンを簡単に指定できます。これらの機能の詳細については、TypeScript 「3.7 リリースノート」を参照してください。具体的には、オプションの連鎖と Nullish 結合の 2 つの機能です。

CDK アプリケーションの構築と実行

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

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

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

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

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

ドキュメントの表記規則

CDK ライブラリの操作

で JavaScript

AWS CDK での の操作 TypeScript