これは AWS CDK v2 デベロッパーガイドです。旧版の CDK v1 は 2022 年 6 月 1 日にメンテナンスを開始し、2023 年 6 月 1 日にサポートを終了しました。 翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # JavaScript での AWS CDK の使用 JavaScript は AWS CDK で完全にサポートされているクライアント言語であり、安定していると見なされます。JavaScript で AWS クラウド開発キット (AWS CDK) を操作するには、[Node.js](https://nodejs.org/) や Node Package Manager () などの使い慣れたツールを使用します`npm`。このガイドの例では NPM を使用していますが、必要に応じて [Yarn](https://yarnpkg.com/) を使用することもできます。 AWS コンストラクトライブラリを構成するモジュールは、NPM リポジトリ [npmjs.org](https://www.npmjs.com/) を介して配布されます。 任意のエディタまたは IDE を使用できます。多くの AWS CDK デベロッパーは [Visual Studio Code](https://code.visualstudio.com/) (または同等のオープンソースの [VSCodium](https://vscodium.com/)) を使用しています。このコードは JavaScript を十分にサポートしています。 ## JavaScript の使用を開始する AWS CDK を使用するには、 AWS アカウントと認証情報があり、Node.js と AWS CDK Toolkit がインストールされている必要があります。[AWS 「CDK の開始方法」を参照してください](getting-started.md)。 JavaScript AWS CDK アプリケーションには、これら以外の追加の前提条件は必要ありません。 **注記** サードパーティー言語の廃止: 言語バージョンは、ベンダーまたはコミュニティによって共有される EOL (製品終了) までのみサポートされ、事前の通知によって変更されます。 ## プロジェクトの作成 空のディレクトリ`cdk init`で を呼び出して、新しい AWS CDK プロジェクトを作成します。`--language` オプションを使用して `javascript` を指定します。 ``` $ mkdir my-project $ cd my-project $ cdk init app --language javascript ``` プロジェクトを作成すると、[aws-cdk-lib](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib-readme.html) モジュールおよびその依存関係もインストールされます。 `cdk init` はプロジェクトフォルダの名前を使用し、クラス、サブフォルダ、ファイルなどのプロジェクトのさまざまな要素に名前を付けます。フォルダ名に含まれるハイフンはアンダースコアに変換されます。ただし、それ以外の場合、名前は JavaScript 識別子の形式に従う必要があります。例えば、数字で始まったり、スペースを含めたりすることはできません。 ## ローカル `cdk` の使用 ほとんどの場合、このガイドでは、CDK Toolkit をグローバルにインストールすることを前提としており (`npm install -g aws-cdk`)、提供されたコマンド例 (`cdk synth` など) はこの前提に従います。このアプローチによって CDK Toolkit を最新の状態に保つことが容易になり、CDK は下位互換性に厳格なアプローチを取っているため、常に最新バージョンを使用するリスクは一般的にほとんどありません。 一部のチームは、CDK Toolkit などのツールを含め、各プロジェクト内のすべての依存関係を指定することを好みます。この実践は、このようなコンポーネントを特定のバージョンに固定し、チームのすべてのデベロッパー (および CI/CD 環境) がそれらのバージョンのみを使用できるようにします。変更になりうる原因がなくなり、ビルドおよびデプロイの一貫性および再現性が向上します。 CDK には JavaScript プロジェクトテンプレートの `package.json` に CDK Toolkit の依存関係が含まれているため、このアプローチを使用する場合、プロジェクトを変更する必要はありません。アプリの構築および `cdk` コマンドの発行には若干異なるコマンドを使用することのみが必要です。 | 運用 | グローバルツールの使用 | ローカルツールの使用 | | --- | --- | --- | | **プロジェクトの初期化** | `cdk init --language javascript` | `npx aws-cdk init --language javascript` | | **CDK Toolkit コマンドを実行する** | `cdk …​` | `npm run cdk …​`、または `npx aws-cdk …​` | 現在のプロジェクトにローカルにインストールされている CDK Toolkit のバージョンが存在する場合、`npx aws-cdk` はそれを実行します。グローバルインストールがある場合、それにフォールバックします。グローバルインストールが存在しない場合、`npx` は CDK Toolkit の一時コピーをダウンロードしてそれを実行します。`@` 構文を使用して CDK Toolkit の任意のバージョンを指定できます。`npx aws-cdk@1.120 --version` は `1.120.0` を出力します。 **ヒント** ローカル CDK Toolkit のインストールで `cdk` コマンドを使用できるように、エイリアスを設定します。 ``` $ alias cdk="npx aws-cdk" ``` ``` doskey cdk=npx aws-cdk $* ``` ## AWS コンストラクトライブラリモジュールの管理 Node Package Manager (`npm`) を使用して、アプリケーションで使用する AWS コンストラクトライブラリモジュール、および必要なその他のパッケージをインストールおよび更新します。(必要に応じて `npm` ではなく、`yarn` を使用できます) `npm` は、それらのモジュールの依存関係も自動的にインストールします。 ほとんどの AWS CDK コンストラクトは、 という名前のメイン CDK パッケージにあります。これは`aws-cdk-lib`、 によって作成された新しいプロジェクトのデフォルトの依存関係です`cdk init`。上位レベルのコンストラクトがまだ開発中である「実験 AWS 」コンストラクトライブラリモジュールは、 のように名前が付けられます`aws-cdk-lib/-alpha`。サービス名には *aws-* のプレフィックスがあります。モジュールの名前が不明な場合、[NPM で検索します](https://www.npmjs.com/search?q=%40aws-cdk)。 **注記** [CDK API リファレンス](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html)には、パッケージ名も表示されます。 たとえば、次のコマンドは、 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 ``` JavaScript では、NPM を使用してモジュールをインストールするために使用するときと同じ名前で、モジュールをコードにインポートします。 AWS CDK クラスと AWS コンストラクトライブラリモジュールをアプリケーションにインポートするときは、次のプラクティスをお勧めします。これらのガイドラインに従うことで、コードが他の AWS CDK アプリケーションと一貫性を持ち、理解しやすくなります。 + ES6-style `import` ディレクティブではなく、`require()` を使用します。Node.js の古いバージョンは ES6 インポートをサポートしていないため、古い構文を使用するとより広範囲に互換性があります。(ES6 インポートを使用する場合、[esm](https://www.npmjs.com/package/esm) を使用してプロジェクトがサポートされているすべての Node.js のバージョンと互換性を持たせます) + 一般的に、`aws-cdk-lib` から個々のクラスをインポートします。 ``` const { App, Stack } = require('aws-cdk-lib'); ``` + `aws-cdk-lib` から多くのクラスが必要な場合、個々のクラスをインポートするのではなく、`cdk` の名前空間エイリアスを使用できます。両方を実行しないでください。 ``` const cdk = require('aws-cdk-lib'); ``` + 一般的に、短い名前空間エイリアスを使用して AWS コンストラクトライブラリをインポートします。 ``` const { s3 } = require('aws-cdk-lib/aws-s3'); ``` ## JavaScript の依存関係の管理 JavaScript CDK プロジェクトでは、依存関係はプロジェクトのメインディレクトリの `package.json` ファイルで指定されます。コア AWS CDK モジュールは、 という 1 つの`NPM`パッケージにあります`aws-cdk-lib`。 `npm install` を使用してパッケージをインストールすると、NPM はパッケージを `package.json` に記録します。 必要に応じて、NPM の代わりに Yarn を使用できます。ただし、CDK は Yarn のプラグアンドプレイモードをサポートしていません。このモードは、Yarn 2 のデフォルトモードです。プロジェクトの `.yarnrc.yml` ファイルに次のものを追加し、この機能をオフにします。 ``` nodeLinker: node-modules ``` ### CDK アプリケーション 次の例は、`cdk init --language typescript` コマンドで生成された `package.json` ファイルです。JavaScript 用に生成されたファイルは似ていますが、TypeScript 関連のエントリがありません。 ``` { "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 変更が発生する可能性があるため、^ または \$1 を使用しないでください。 `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 パッケージと互換性があることをアドバタイズする最低バージョンを正確に (^ または \$1 なしで) 指定します。これを実践すると、テストがこれらのバージョンに対して実行されていることを確認できます。これにより、新しいバージョンでのみ見つかった機能を誤って使用した場合、テストで検出できます。 **警告** `peerDependencies` は NPM 7 以降でのみ自動的にインストールされます。NPM 6 以前または Yarn を使用している場合、依存関係の依存関係を `devDependencies` に含める必要があります。そうしないと、インストールされないため、未解決のピア依存関係に関する警告が表示されます。 ### 依存関係のインストールと更新 次のコマンドを実行してプロジェクトの依存関係をインストールします。 **Example** ``` # Install the latest version of everything that matches the ranges in 'package.json' npm install # Install the same exact dependency versions as recorded in 'package-lock.json' npm ci ``` ``` # Install the latest version of everything that matches the ranges in 'package.json' yarn upgrade # Install the same exact dependency versions as recorded in 'yarn.lock' yarn install --frozen-lockfile ``` インストールされたモジュールを更新するには、前述の `npm install` コマンドと `yarn upgrade` コマンドを使用できます。いずれのコマンドも、`package.json` のルールを満たす最新バージョンに `node_modules` のパッケージを更新します。ただし、`package.json` 自体は更新されません。新しい最小バージョンを設定するために行うことができます。GitHub でパッケージをホストする場合、`package.json` を自動的に更新するように [Dependabot バージョンの更新プログラム](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates)を設定できます。または、[npm-check-updates ](https://www.npmjs.com/package/npm-check-updates) を使用します。 **重要** 設計上、依存関係をインストールまたは更新するとき、NPM および Yarn は `package.json` で指定された要件を満たすすべてのパッケージの最新バージョンを選択します。これらのバージョンが (誤ってまたは意図的に) 破損するリスクが常にあります。プロジェクトの依存関係を更新した後は、徹底的なテストを行ってください。 ## AWS JavaScript の CDK イディオム ### Props すべての AWS コンストラクトライブラリクラスは、3 つの引数を使用してインスタンス化されます。コンストラクトが定義されている*スコープ* (コンストラクトツリー内の親）、*ID*、*props*、コンストラクトが作成する AWS リソースの設定に使用するキーと値のペアのバンドルです。他のクラスやメソッドでは、引数に「属性のバンドル」パターンも使用されます。 JavaScript オートコンプリートが適切な IDE またはエディタを使用すると、プロパティ名のスペルミスを防止することができます。コンストラクトが `encryptionKeys` プロパティを予想し、ユーザーがそれを `encryptionkeys` とスペルした場合、コンストラクトをインスタンス化するときに意図した値に合格しません。プロパティが必要な場合は合成時にエラーが発生するか、オプションの場合はプロパティが静的に無視される可能性があります。後者の場合、上書きを意図しているデフォルトの動作が発生する場合があります。ここでは十分に注意してください。 AWS コンストラクトライブラリクラスをサブクラス化する場合 (または props のような引数を取るメソッドを上書きする場合）、独自の使用のために追加のプロパティを受け入れることができます。そのコードではアクセスされないため、これらの値は親クラスまたは上書きされたメソッドによって無視されます。したがって、一般的に受け取ったすべての props を渡すことができます。 AWS CDK の今後のリリースでは、独自のプロパティに使用した名前の新しいプロパティが同時に追加される可能性があります。受け取る値を継承チェーンの上方に渡すと、予期しない動作が発生する可能性があります。プロパティを削除または `undefined` に設定した状態で受け取った props の浅いコピーを渡す方が安全です。例えば、次のようになります。 ``` super(scope, name, {...props, encryptionKeys: undefined}); ``` または、プロパティに名前を付けてコンストラクトに属していることを明確にします。これにより、将来の AWS CDK リリースでプロパティと衝突する可能性は低くなります。多数ある場合、適切に名前が付けられたオブジェクトを 1 つ使用して保持します。 ### 欠落した値 オブジェクト (`props` など) の欠落値は、JavaScript で `undefined` の値があります。これらに対処する場合、通常の手法が適用されます。例えば、定義されていないある値のプロパティにアクセスするための一般的なイディオムは次のとおりです。 ``` // a may be undefined, but if it is not, it may have an attribute b // c is undefined if a is undefined, OR if a doesn't have an attribute b let c = a && a.b; ``` ただし、`a` に `undefined` 以外の他の「falsy」値が含まれる可能性がある場合、テストをより明確にすることが推奨されます。こちらでは、`null` および `undefined` は等しいため、両方とも一度にテストできるという事実を活用します。 ``` let c = a == null ? a : a.b; ``` **ヒント** Node.js 14.0 以降では、未定義の値の処理を簡素化できる新しい演算子がサポートされています。詳細については、「[オプションの連鎖](https://github.com/tc39/proposal-optional-chaining/blob/master/README.md)」および「[NULL 合体](https://github.com/tc39/proposal-nullish-coalescing/blob/master/README.md)」の提案を参照してください。 ## JavaScript で TypeScript 例の使用 [TypeScript](https://www.typescriptlang.org/) は AWS CDK の開発に使用する言語であり、アプリケーションの開発で最初にサポートされている言語であるため、使用可能な AWS CDK コード例は TypeScript で記述されています。これらのコード例は JavaScript デベロッパーにとって良いリソースです。コードの TypeScript 固有の部分を削除するのみです。 TypeScript スニペットは、新しい ECMAScript の `import` および `export` キーワードを使用し、他のモジュールからオブジェクトをインポートして、現在のモジュール外で利用できるようにオブジェクトを宣言することがよくあります。Node.js は、最新リリースでこれらのキーワードのサポートを開始したばかりです。使用している (またはサポートする) Node.js のバージョンによっては、古い構文を使用するためにインポートおよびエクスポートを書き換える場合があります。 インポートは `require()` 関数への呼び出しに置き換えることができます。 **Example** ``` import * as cdk from 'aws-cdk-lib'; import { Bucket, BucketPolicy } from 'aws-cdk-lib/aws-s3'; ``` ``` const cdk = require('aws-cdk-lib'); const { Bucket, BucketPolicy } = require('aws-cdk-lib/aws-s3'); ``` エクスポートは `module.exports` オブジェクトに割り当てることができます。 **Example** ``` export class Stack1 extends cdk.Stack { // ... } export class Stack2 extends cdk.Stack { // ... } ``` ``` class Stack1 extends cdk.Stack { // ... } class Stack2 extends cdk.Stack { // ... } module.exports = { Stack1, Stack2 } ``` **注記** 古い形式のインポートおよびエクスポートを使用する代わりに、[esm](https://www.npmjs.com/package/esm) モジュールを使用します。 インポートおよびエクスポートの対応が済んだら、実際のコードを触れることができます。一般的に使用される以下の TypeScript 機能を使用する場合があります。 + 型注釈 + インターフェイス定義 + タイプ変換/キャスト + アクセス修飾子 変数、クラスメンバー、関数パラメータ、関数戻り型に対して型注釈を指定できます。変数、パラメータ、メンバーの場合、識別子の後にコロンおよび型を配置することで型を指定します。関数の戻り値は関数署名に従い、コロンおよび型で構成されます。 型注釈付きコードを JavaScript に変換するには、コロンおよび型を削除します。クラスメンバーは JavaScript に値を含める必要があります。TypeScript に型注釈のみがある場合、`undefined` に設定します。 **Example** ``` var encrypted: boolean = true; class myStack extends cdk.Stack { bucket: s3.Bucket; // ... } function makeEnv(account: string, region: string) : object { // ... } ``` ``` var encrypted = true; class myStack extends cdk.Stack { bucket = undefined; // ... } function makeEnv(account, region) { // ... } ``` TypeScript では、必須プロパティおよびオプションのプロパティのバンドル、ならびにそれぞれの型に名前を付けるため、インターフェイスが使用されます。その後、インターフェイス名を型注釈として使用できます。TypeScript は、(例えば) 関数の引数として使用するオブジェクトに、適切な型に必要なプロパティがあることを確認します。 ``` interface myFuncProps { code: lambda.Code, handler?: string } ``` JavaScript にはインターフェイス機能がないため、型注釈を削除したらインターフェイス宣言を完全に削除します。 関数またはメソッドが汎用型 (`object` など) を返しても、より一般的な型のインターフェイスに含まれていないプロパティまたはメソッドにアクセスするため、値をより具体的な子タイプとして扱う場合、TypeScript では、`as` を使用して値を*キャスト*したら、タイプまたはインターフェイス名も同様に処理できます。JavaScript はこれをサポートしていない (または必要としない) ため、`as` および次の識別子のみを削除します。あまり一般的ではないキャスト構文では、`` の括弧内に型名を使用します。これらのキャストも削除する必要があります。 最後に、TypeScript はクラスのメンバー用の `public`、`protected`、`private` アクセス修飾子をサポートします。JavaScript のすべてのクラスメンバーはパブリックです。これらの修飾子は見つけたら削除してください。 これらの TypeScript 機能を特定して削除する方法を知っていると、短い TypeScript スニペットを JavaScript に適応させる上でかなり有利になります。ただし、他の TypeScript 機能を使用する可能性が高いため、この方法で長い TypeScript の例を変換することは現実的ではない場合があります。このような状況では、[Sucrase](https://github.com/alangpierce/sucrase) をお勧めします。例えば、コードが未定義の変数を使用している場合、`tsc` とは違って Sucrase は申し立てることはありません。構文的に有効な場合、いくつかの例外を除くと Sucrase は JavaScript に変換できます。単独で実行できないスニペットを変換するのうえで特に重宝されます。 ## TypeScript への移行 多くの JavaScript デベロッパーは、プロジェクトが大型化かつ複雑化すると [TypeScript](https://www.typescriptlang.org/) に移行します。TypeScript は JavaScript のスーパーセットです。JavaScript コードはすべて有効な TypeScript コードであるため、コードを変更する必要はありません。また、サポートされている AWS CDK 言語でもあります。型注釈やその他の TypeScript 機能はオプションであり、値を見つけたら AWS CDK アプリに追加できます。TypeScript は、オプション連鎖や NULL 合体など、確定する前に新しい JavaScript 機能を早期にアクセスできるようにし、Node.js のアップグレードは不要です。 TypeScript の「形状ベース」のインターフェイスは、オブジェクト内の必須プロパティおよびオプションのプロパティ (およびそのタイプ) のバンドルを定義し、コードの記述中に一般的なミスをキャッチできるようにして、IDE が堅牢なオートコンプリートやその他のリアルタイムのコーディングアドバイスを提供しやすくします。 TypeScript でのコーディングにはステップが追加されることなく、TypeScript コンパイラの `tsc` を使用してアプリをコンパイルします。一般的な AWS CDK アプリの場合、コンパイルには最大で数秒かかります。 既存の JavaScript AWS CDK アプリを TypeScript に移行する最も簡単な方法は、 を使用して新しい TypeScript プロジェクトを作成し`cdk init app --language typescript`、ソースファイル (および AWS Lambda 関数のソースコードなどのアセットなど、その他の必要なファイル) を新しいプロジェクトにコピーすることです。JavaScript ファイルの名前が `.ts` で終了するように変更し、TypeScript で開発を開始します。