の開始方法 TypeScript 「プロジェクトの作成」ローカル tscとの使用 cdk AWS コンストラクトライブラリモジュールの管理での依存関係の管理 TypeScript AWS CDK での idioms TypeScript 構築、合成、デプロイ

AWS CDK でのの使用 TypeScript

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

操作	グローバルツールを使用する	ローカルツールを使用する
プロジェクトを初期化する	`cdk init --language typescript`	`npx aws-cdk init --language typescript`
ビルド	`tsc`	`npm run build`
CDK Toolkit コマンドを実行する	`cdk ...`	`npm run cdk ...` or `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) を使用して、アプリケーションで使用する Construct Library 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-styleimportディレクティブを使用します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 に記録します。

必要に応じて、NPM の代わりに Yarn を使用できます。ただし、CDK は Yarn 2 plug-and-play のデフォルトモードである Yarn モードをサポートしていません。以下をプロジェクトの .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 を含む alpha construct ライブラリモジュールの正確なバージョンを指定します。peerDependencies を使用すると、ツリー内のすべての CDK ライブラリのコピーが 1 node_modules つだけになります。

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

警告

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

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

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

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

重要

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

AWS CDK での idioms TypeScript

プロンプト

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

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

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

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

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


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

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

欠落した値

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

構築、合成、デプロイ

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

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

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

AWS CDK アプリケーションで定義されたスタックは、合成して個別にデプロイすることも、以下のコマンドを使用してまとめてデプロイすることもできます。通常、プロジェクトを発行するときは、プロジェクトのメインディレクトリにいる必要があります。

cdk synth: AWS CDK アプリケーションの 1 つ以上のスタックから AWS CloudFormation テンプレートを合成します。
cdk deploy: AWS CDK アプリケーション内の 1 つ以上のスタックによって定義されたリソースをにデプロイします AWS。

1 つのコマンドで合成またはデプロイする複数のスタックの名前を指定できます。アプリケーションが 1 つのスタックのみを定義している場合は、指定する必要はありません。


cdk synth                 # app defines single stack
cdk deploy Happy Grumpy   # app defines two or more stacks; two are deployed

また、ワイルドカード * (任意の文字数) と ? (任意の 1 文字) を使用して、パターンでスタックを識別することもできます。ワイルドカードを使用する場合は、パターンを引用符で囲みます。そうしないと、シェルは AWS CDK Toolkit に渡す前に、現在のディレクトリ内のファイルの名前に拡張しようとする可能性があります。


cdk synth "Stack?"    # Stack1, StackA, etc.
cdk deploy "*Stack"   # PipeStack, LambdaStack, etc.

ヒント

デプロイする前にスタックを明示的に合成する必要はありません。はこのステップcdk deployを実行して、最新のコードがデプロイされることを確認します。

cdk コマンドの完全なドキュメントについては、「」を参照してくださいAWS CDK ツールキット (cdk コマンド）。

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

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

ドキュメントの表記規則

の使用 AWS CDK

内 JavaScript

AWS CDK での の使用 TypeScript