This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on June 1, 2022 and ended support on June 1, 2023. # Work with the AWS CDK library Import and use the AWS Cloud Development Kit (AWS CDK) library to define your AWS Cloud infrastructure with a [supported programming language](languages.md). ## Import the AWS CDK Library The [AWS CDK Library](libraries.md) is often referred to by its TypeScript package name of `aws-cdk-lib`. The actual package name varies by language. The following is an example of how to install and import the CDK Library: **Example** | | | | --- |--- | | **Install** | `npm install aws-cdk-lib` | | **Import** | `import * as cdk from 'aws-cdk-lib';` | | | | | --- |--- | | **Install** | `npm install aws-cdk-lib` | | **Import** | `const cdk = require('aws-cdk-lib');` | | | | | --- |--- | | **Install** | `python -m pip install aws-cdk-lib` | | **Import** | `import aws_cdk as cdk` | | | | | --- |--- | | **In `pom.xml`, add** | `Group software.amazon.awscdk; artifact aws-cdk-lib` | | **Import** | `import software.amazon.awscdk.App;` | | | | | --- |--- | | **Install** | `dotnet add package Amazon.CDK.Lib` | | **Import** | `using Amazon.CDK;` | | | | | --- |--- | | **Install** | `go get github.com/aws/aws-cdk-go/awscdk/v2` | | **Import** | 
import (
  "github.com/aws/aws-cdk-go/awscdk/v2"
)
| The `construct` base class and supporting code is in the `constructs` library. Experimental constructs, where the API is still undergoing refinement, are distributed as separate modules. ## Using the AWS CDK API Reference Use the [AWS CDK API reference](libraries.md#libraries-reference) as you develop with the AWS CDK. Each module’s reference material is broken into the following sections. + *Overview*: Introductory material you’ll need to know to work with the service in the AWS CDK, including concepts and examples. + *Constructs*: Library classes that represent one or more concrete AWS resources. These are the "curated" (L2) resources or patterns (L3 resources) that provide a high-level interface with sane defaults. + *Classes*: Non-construct classes that provide functionality used by constructs in the module. + *Structs*: Data structures (attribute bundles) that define the structure of composite values such as properties (the `props` argument of constructs) and options. + *Interfaces*: Interfaces, whose names all begin with "I", define the absolute minimum functionality for the corresponding construct or other class. The CDK uses construct interfaces to represent AWS resources that are defined outside your AWS CDK app and referenced by methods such as `Bucket.fromBucketArn()`. + *Enums*: Collections of named values for use in specifying certain construct parameters. Using an enumerated value allows the CDK to check these values for validity during synthesis. + *CloudFormation Resources*: These L1 constructs, whose names begin with "Cfn", represent exactly the resources defined in the CloudFormation specification. They are automatically generated from that specification with each CDK release. Each L2 or L3 construct encapsulates one or more CloudFormation resources. + *CloudFormation Property Types*: The collection of named values that define the properties for each CloudFormation Resource. ## Interfaces compared with construct classes The AWS CDK uses interfaces in a specific way that may not be obvious even if you are familiar with interfaces as a programming concept. The AWS CDK supports using resources defined outside CDK applications using methods such as `Bucket.fromBucketArn()`. External resources cannot be modified and may not have all the functionality available with resources defined in your CDK app using e.g. the `Bucket` class. Interfaces, then, represent the bare minimum functionality available in the CDK for a given AWS resource type, *including external resources*. When instantiating resources in your CDK app, then, you should always use concrete classes such as `Bucket`. When specifying the type of an argument you are accepting in one of your own constructs, use the interface type such as `IBucket` if you are prepared to deal with external resources (that is, you won’t need to change them). If you require a CDK-defined construct, specify the most general type you can use. Some interfaces are minimum versions of properties or options bundles associated with specific classes, rather than constructs. Such interfaces can be useful when subclassing to accept arguments that you’ll pass on to your parent class. If you require one or more additional properties, you’ll want to implement or derive from this interface, or from a more specific type. **Note** Some programming languages supported by the AWS CDK don’t have an interface feature. In these languages, interfaces are just ordinary classes. You can identify them by their names, which follow the pattern of an initial "I" followed by the name of some other construct (e.g. `IBucket`). The same rules apply. ## Managing dependencies Dependencies for your AWS CDK app or library are managed using package management tools. These tools are commonly used with the programming languages. Typically, the AWS CDK supports the language’s standard or official package management tool if there is one. Otherwise, the AWS CDK will support the language’s most popular or widely supported one. You may also be able to use other tools, especially if they work with the supported tools. However, official support for other tools is limited. The AWS CDK supports the following package managers: | Language | Supported package management tool | | --- | --- | | TypeScript/JavaScript | NPM (Node Package Manager) or Yarn | | Python | PIP (Package Installer for Python) | | Java | Maven | | C\$1 | NuGet | | Go | Go modules | When you create a new project using the AWS CDK CLI `cdk init` command, dependencies for the CDK core libraries and stable constructs are automatically specified. For more information on managing dependencies for supported programming languages, see the following: + [Managing dependencies in TypeScript](work-with-cdk-typescript.md#work-with-cdk-typescript-dependencies). + [Managing dependencies in JavaScript](work-with-cdk-javascript.md#work-with-cdk-javascript-dependencies). + [Managing dependencies in Python](work-with-cdk-python.md#work-with-cdk-python-dependencies). + [Managing dependencies in Java](work-with-cdk-java.md#work-with-cdk-java-dependencies). + [Managing dependencies in C\$1](work-with-cdk-csharp.md#work-with-cdk-csharp-dependencies). + [Managing dependencies in Go](work-with-cdk-go.md#work-with-cdk-go-dependencies). ## Comparing AWS CDK in TypeScript with other languages TypeScript was the first language supported for developing AWS CDK applications. Therefore, a substantial amount of example CDK code is written in TypeScript. If you are developing in another language, it might be useful to compare how AWS CDK code is implemented in TypeScript compared to your language of choice. This can help you use the examples throughout documentation. ## Importing a module **Example** TypeScript supports importing either an entire namespace, or individual objects from a namespace. Each namespace includes constructs and other classes for use with a given AWS service. ``` // Import main CDK library as cdk import * as cdk from 'aws-cdk-lib'; // ES6 import preferred in TS const cdk = require('aws-cdk-lib'); // Node.js require() preferred in JS // Import specific core CDK classes import { Stack, App } from 'aws-cdk-lib'; const { Stack, App } = require('aws-cdk-lib'); // Import AWS S3 namespace as s3 into current namespace import { aws_s3 as s3 } from 'aws-cdk-lib'; // TypeScript const s3 = require('aws-cdk-lib/aws-s3'); // JavaScript // Having imported cdk already as above, this is also valid const s3 = cdk.aws_s3; // Now use s3 to access the S3 types const bucket = s3.Bucket(...); // Selective import of s3.Bucket import { Bucket } from 'aws-cdk-lib/aws-s3'; // TypeScript const { Bucket } = require('aws-cdk-lib/aws-s3'); // JavaScript // Now use Bucket to instantiate an S3 bucket const bucket = Bucket(...); ``` Like TypeScript, Python supports namespaced module imports and selective imports. Namespaces in Python look like **aws\$1cdk.** *xxx*, where *xxx* represents an AWS service name, such as **s3** for Amazon S3. (Amazon S3 is used in these examples). ``` # Import main CDK library as cdk import aws_cdk as cdk # Selective import of specific core classes from aws_cdk import Stack, App # Import entire module as s3 into current namespace import aws_cdk.aws_s3 as s3 # s3 can now be used to access classes it contains bucket = s3.Bucket(...) # Selective import of s3.Bucket into current namespace from aws_cdk.s3 import Bucket # Bucket can now be used to instantiate a bucket bucket = Bucket(...) ``` Java’s imports work differently from TypeScript’s. Each import statement imports either a single class name from a given package, or all classes defined in that package (using `\*`). Classes may be accessed using either the class name by itself if it has been imported, or the *qualified* class name including its package. Libraries are named like `software.amazon.awscdk.services.xxx` for the AWS Construct Library (the main library is `software.amazon.awscdk`). The Maven group ID for AWS CDK packages is `software.amazon.awscdk`. ``` // Make certain core classes available import software.amazon.awscdk.Stack; import software.amazon.awscdk.App; // Make all Amazon S3 construct library classes available import software.amazon.awscdk.services.s3.*; // Make only Bucket and EventType classes available import software.amazon.awscdk.services.s3.Bucket; import software.amazon.awscdk.services.s3.EventType; // An imported class may now be accessed using the simple class name (assuming that name // does not conflict with another class) Bucket bucket = Bucket.Builder.create(...).build(); // We can always use the qualified name of a class (including its package) even without an // import directive software.amazon.awscdk.services.s3.Bucket bucket = software.amazon.awscdk.services.s3.Bucket.Builder.create(...) .build(); // Java 10 or later can use var keyword to avoid typing the type twice var bucket = software.amazon.awscdk.services.s3.Bucket.Builder.create(...) .build(); ``` In C\$1, you import types with the `using` directive. There are two styles. One gives you access to all the types in the specified namespace by using their plain names. With the other, you can refer to the namespace itself by using an alias. Packages are named like `Amazon.CDK.AWS.xxx` for AWS Construct Library packages. (The core module is `Amazon.CDK`.) ``` // Make CDK base classes available under cdk using cdk = Amazon.CDK; // Make all Amazon S3 construct library classes available using Amazon.CDK.AWS.S3; // Now we can access any S3 type using its name var bucket = new Bucket(...); // Import the S3 namespace under an alias using s3 = Amazon.CDK.AWS.S3; // Now we can access an S3 type through the namespace alias var bucket = new s3.Bucket(...); // We can always use the qualified name of a type (including its namespace) even without a // using directive var bucket = new Amazon.CDK.AWS.S3.Bucket(...); ``` Each AWS Construct Library module is provided as a Go package. ``` import ( "github.com/aws/aws-cdk-go/awscdk/v2" // CDK core package "github.com/aws/aws-cdk-go/awscdk/v2/awss3" // AWS S3 construct library module ) // now instantiate a bucket bucket := awss3.NewBucket(...) // use aliases for brevity/clarity import ( cdk "github.com/aws/aws-cdk-go/awscdk/v2" // CDK core package s3 "github.com/aws/aws-cdk-go/awscdk/v2/awss3" // AWS S3 construct library module ) bucket := s3.NewBucket(...) ``` ## Instantiating a construct AWS CDK construct classes have the same name in all supported languages. Most languages use the `new` keyword to instantiate a class (Python and Go do not). Also, in most languages, the keyword `this` refers to the current instance. (Python uses `self` by convention.) You should pass a reference to the current instance as the `scope` parameter to every construct you create. The third argument to an AWS CDK construct is `props`, an object containing attributes needed to build the construct. This argument may be optional, but when it is required, the supported languages handle it in idiomatic ways. The names of the attributes are also adapted to the language’s standard naming patterns. **Example** ``` // Instantiate default Bucket const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket'); // Instantiate Bucket with bucketName and versioned properties const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket', { bucketName: 'amzn-s3-demo-bucket', versioned: true, }); // Instantiate Bucket with websiteRedirect, which has its own sub-properties const bucket = new s3.Bucket(this, 'amzn-s3-demo-bucket', { websiteRedirect: {host: 'aws.amazon.com'}}); ``` Python doesn’t use a `new` keyword when instantiating a class. The properties argument is represented using keyword arguments, and the arguments are named using `snake_case`. If a props value is itself a bundle of attributes, it is represented by a class named after the property, which accepts keyword arguments for the subproperties. In Python, the current instance is passed to methods as the first argument, which is named `self` by convention. ``` # Instantiate default Bucket bucket = s3.Bucket(self, "amzn-s3-demo-bucket") # Instantiate Bucket with bucket_name and versioned properties bucket = s3.Bucket(self, "amzn-s3-demo-bucket", bucket_name="amzn-s3-demo-bucket", versioned=true) # Instantiate Bucket with website_redirect, which has its own sub-properties bucket = s3.Bucket(self, "amzn-s3-demo-bucket", website_redirect=s3.WebsiteRedirect( host_name="aws.amazon.com")) ``` In Java, the props argument is represented by a class named `XxxxProps` (for example, `BucketProps` for the `Bucket` construct’s props). You build the props argument using a builder pattern. Each `XxxxProps` class has a builder. There is also a convenient builder for each construct that builds the props and the construct in one step, as shown in the following example. Props are named the same as in TypeScript, using `camelCase`. ``` // Instantiate default Bucket Bucket bucket = Bucket(self, "amzn-s3-demo-bucket"); // Instantiate Bucket with bucketName and versioned properties Bucket bucket = Bucket.Builder.create(self, "amzn-s3-demo-bucket") .bucketName("amzn-s3-demo-bucket").versioned(true) .build(); # Instantiate Bucket with websiteRedirect, which has its own sub-properties Bucket bucket = Bucket.Builder.create(self, "amzn-s3-demo-bucket") .websiteRedirect(new websiteRedirect.Builder() .hostName("aws.amazon.com").build()) .build(); ``` In C\$1, props are specified using an object initializer to a class named `XxxxProps` (for example, `BucketProps` for the `Bucket` construct’s props). Props are named similarly to TypeScript, except using `PascalCase`. It is convenient to use the `var` keyword when instantiating a construct, so you don’t need to type the class name twice. However, your local code style guide may vary. ``` // Instantiate default Bucket var bucket = Bucket(self, "amzn-s3-demo-bucket"); // Instantiate Bucket with BucketName and Versioned properties var bucket = Bucket(self, "amzn-s3-demo-bucket", new BucketProps { BucketName = "amzn-s3-demo-bucket", Versioned = true}); // Instantiate Bucket with WebsiteRedirect, which has its own sub-properties var bucket = Bucket(self, "amzn-s3-demo-bucket", new BucketProps { WebsiteRedirect = new WebsiteRedirect { HostName = "aws.amazon.com" }}); ``` To create a construct in Go, call the function `NewXxxxxx` where `Xxxxxxx` is the name of the construct. The constructs' properties are defined as a struct. In Go, all construct parameters are pointers, including values like numbers, Booleans, and strings. Use the convenience functions like `jsii.String` to create these pointers. ``` // Instantiate default Bucket bucket := awss3.NewBucket(stack, jsii.String("amzn-s3-demo-bucket"), nil) // Instantiate Bucket with BucketName and Versioned properties bucket1 := awss3.NewBucket(stack, jsii.String("amzn-s3-demo-bucket"), &awss3.BucketProps{ BucketName: jsii.String("amzn-s3-demo-bucket"), Versioned: jsii.Bool(true), }) // Instantiate Bucket with WebsiteRedirect, which has its own sub-properties bucket2 := awss3.NewBucket(stack, jsii.String("amzn-s3-demo-bucket"), &awss3.BucketProps{ WebsiteRedirect: &awss3.RedirectTarget{ HostName: jsii.String("aws.amazon.com"), }}) ``` ## Accessing members It is common to refer to attributes or properties of constructs and other AWS CDK classes and use these values as, for example, inputs to build other constructs. The naming differences described previously for methods apply here also. Furthermore, in Java, it is not possible to access members directly. Instead, a getter method is provided. **Example** Names are `camelCase`. ``` bucket.bucketArn ``` Names are `snake_case`. ``` bucket.bucket_arn ``` A getter method is provided for each property; these names are `camelCase`. ``` bucket.getBucketArn() ``` Names are `PascalCase`. ``` bucket.BucketArn ``` Names are `PascalCase`. ``` bucket.BucketArn ``` ## Enum constants Enum constants are scoped to a class, and have uppercase names with underscores in all languages (sometimes referred to as `SCREAMING_SNAKE_CASE`). Since class names also use the same casing in all supported languages except Go, qualified enum names are also the same in these languages. ``` s3.BucketEncryption.KMS_MANAGED ``` In Go, enum constants are attributes of the module namespace and are written as follows. ``` awss3.BucketEncryption_KMS_MANAGED ``` ## Object interfaces The AWS CDK uses TypeScript object interfaces to indicate that a class implements an expected set of methods and properties. You can recognize an object interface because its name starts with `I`. A concrete class indicates the interfaces that it implements by using the `implements` keyword. **Example** JavaScript doesn’t have an interface feature. You can ignore the `implements` keyword and the class names following it. ``` import { IAspect, IConstruct } from 'aws-cdk-lib'; class MyAspect implements IAspect { public visit(node: IConstruct) { console.log('Visited', node.node.path); } } ``` Python doesn’t have an interface feature. However, for the AWS CDK you can indicate interface implementation by decorating your class with `@jsii.implements(interface)`. ``` from aws_cdk import IAspect, IConstruct import jsii @jsii.implements(IAspect) class MyAspect(): def visit(self, node: IConstruct) -> None: print("Visited", node.node.path) ``` ``` import software.amazon.awscdk.IAspect; import software.amazon.awscdk.IConstruct; public class MyAspect implements IAspect { public void visit(IConstruct node) { System.out.format("Visited %s", node.getNode().getPath()); } } ``` ``` using Amazon.CDK; public class MyAspect : IAspect { public void Visit(IConstruct node) { System.Console.WriteLine($"Visited ${node.Node.Path}"); } } ``` Go structs do not need to explicitly declare which interfaces they implement. The Go compiler determines implementation based on the methods and properties available on the structure. For example, in the following code, `MyAspect` implements the `IAspect` interface because it provides a `Visit` method that takes a construct. ``` type MyAspect struct { } func (a MyAspect) Visit(node constructs.IConstruct) { fmt.Println("Visited", *node.Node().Path()) } ``` # Working with the AWS CDK in TypeScript TypeScript is a fully-supported client language for the AWS Cloud Development Kit (AWS CDK) and is considered stable. Working with the AWS CDK in TypeScript uses familiar tools, including Microsoft’s TypeScript compiler (`tsc`), [Node.js](https://nodejs.org/) and the Node Package Manager (`npm`). You may also use [Yarn](https://yarnpkg.com/) if you prefer, though the examples in this Guide use NPM. The modules comprising the AWS Construct Library are distributed via the NPM repository, [npmjs.org](https://www.npmjs.com/). You can use any editor or IDE. Many AWS CDK developers use [Visual Studio Code](https://code.visualstudio.com/) (or its open-source equivalent [VSCodium](https://vscodium.com/)), which has excellent support for TypeScript. ## Get started with TypeScript To work with the AWS CDK, you must have an AWS account and credentials and have installed Node.js and the AWS CDK Toolkit. See [Getting started with the AWS CDK](getting-started.md). You also need TypeScript itself (version 3.8 or later). If you don’t already have it, you can install it using `npm`. ``` $ npm install -g typescript ``` **Note** If you get a permission error, and have administrator access on your system, try `sudo npm install -g typescript`. Keep TypeScript up to date with a regular `npm update -g typescript`. **Note** Third-party language deprecation: language version is only supported until its EOL (End Of Life) shared by the vendor or community and is subject to change with prior notice. ## Creating a project You create a new AWS CDK project by invoking `cdk init` in an empty directory. Use the `--language` option and specify `typescript`: ``` $ mkdir my-project $ cd my-project $ cdk init app --language typescript ``` Creating a project also installs the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib-readme.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib-readme.html) module and its dependencies. `cdk init` uses the name of the project folder to name various elements of the project, including classes, subfolders, and files. Hyphens in the folder name are converted to underscores. However, the name should otherwise follow the form of a TypeScript identifier; for example, it should not start with a number or contain spaces. ## Using local `tsc` and `cdk` For the most part, this guide assumes you install TypeScript and the CDK Toolkit globally (`npm install -g typescript aws-cdk`), and the provided command examples (such as `cdk synth`) follow this assumption. This approach makes it easy to keep both components up to date, and since both take a strict approach to backward compatibility, there is generally little risk in always using the latest versions. Some teams prefer to specify all dependencies within each project, including tools like the TypeScript compiler and the CDK Toolkit. This practice lets you pin these components to specific versions and ensure that all developers on your team (and your CI/CD environment) use exactly those versions. This eliminates a possible source of change, helping to make builds and deployments more consistent and repeatable. The CDK includes dependencies for both TypeScript and the CDK Toolkit in the TypeScript project template’s `package.json`, so if you want to use this approach, you don’t need to make any changes to your project. All you need to do is use slightly different commands for building your app and for issuing `cdk` commands. | Operation | Use global tools | Use local tools | | --- | --- | --- | | **Initialize project** | `cdk init --language typescript` | `npx aws-cdk init --language typescript` | | **Build** | `tsc` | `npm run build` | | **Run CDK Toolkit command** | `cdk …​` | `npm run cdk …​` or `npx aws-cdk …​` | `npx aws-cdk` runs the version of the CDK Toolkit installed locally in the current project, if one exists, falling back to the global installation, if any. If no global installation exists, `npx` downloads a temporary copy of the CDK Toolkit and runs that. You may specify an arbitrary version of the CDK Toolkit using the `@` syntax: `npx aws-cdk@2.0 --version` prints `2.0.0`. **Tip** Set up an alias so you can use the `cdk` command with a local CDK Toolkit installation. ``` $ alias cdk="npx aws-cdk" ``` ``` doskey cdk=npx aws-cdk $* ``` ## Managing AWS Construct Library modules Use the Node Package Manager (`npm`) to install and update AWS Construct Library modules for use by your apps, as well as other packages you need. (You may use `yarn` instead of `npm` if you prefer.) `npm` also installs the dependencies for those modules automatically. Most AWS CDK constructs are in the main CDK package, named `aws-cdk-lib`, which is a default dependency in new projects created by `cdk init`. "Experimental" AWS Construct Library modules, where higher-level constructs are still under development, are named like `@aws-cdk/-alpha`. The service name has an *aws-* prefix. If you’re unsure of a module’s name, [search for it on NPM](https://www.npmjs.com/search?q=%40aws-cdk). **Note** The [CDK API Reference](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html) also shows the package names. For example, the command below installs the experimental module for AWS CodeStar. ``` $ npm install @aws-cdk/aws-codestar-alpha ``` Some services' Construct Library support is in more than one namespace. For example, besides `aws-route53`, there are three additional Amazon Route 53 namespaces, `aws-route53-targets`, `aws-route53-patterns`, and `aws-route53resolver`. Your project’s dependencies are maintained in `package.json`. You can edit this file to lock some or all of your dependencies to a specific version or to allow them to be updated to newer versions under certain criteria. To update your project’s NPM dependencies to the latest permitted version according to the rules you specified in `package.json`: ``` $ npm update ``` In TypeScript, you import modules into your code under the same name you use to install them using NPM. We recommend the following practices when importing AWS CDK classes and AWS Construct Library modules in your applications. Following these guidelines will help make your code consistent with other AWS CDK applications as well as easier to understand. + Use ES6-style `import` directives, not `require()`. + Generally, import individual classes from `aws-cdk-lib`. ``` import { App, Stack } from 'aws-cdk-lib'; ``` + If you need many classes from `aws-cdk-lib`, you may use a namespace alias of `cdk` instead of importing the individual classes. Avoid doing both. ``` import * as cdk from 'aws-cdk-lib'; ``` + Generally, import AWS service constructs using short namespace aliases. ``` import { aws_s3 as s3 } from 'aws-cdk-lib'; ``` ## Managing dependencies in TypeScript In TypeScript CDK projects, dependencies are specified in the `package.json` file in the project’s main directory. The core AWS CDK modules are in a single `NPM` package called `aws-cdk-lib`. When you install a package using `npm install`, NPM records the package in `package.json` for you. If you prefer, you may use Yarn in place of NPM. However, the CDK does not support Yarn’s plug-and-play mode, which is default mode in Yarn 2. Add the following to your project’s `.yarnrc.yml` file to turn off this feature. ``` nodeLinker: node-modules ``` ### CDK applications The following is an example `package.json` file generated by the `cdk init --language typescript` command: ``` { "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" } } ``` For deployable CDK apps, `aws-cdk-lib` must be specified in the `dependencies` section of `package.json`. You can use a caret (^) version number specifier to indicate that you will accept later versions than the one specified as long as they are within the same major version. For experimental constructs, specify exact versions for the alpha construct library modules, which have APIs that may change. Do not use ^ or \$1 since later versions of these modules may bring API changes that can break your app. Specify versions of libraries and tools needed to test your app (for example, the `jest` testing framework) in the `devDependencies` section of `package.json`. Optionally, use ^ to specify that later compatible versions are acceptable. ### Third-party construct libraries If you’re developing a construct library, specify its dependencies using a combination of the `peerDependencies` and `devDependencies` sections, as shown in the following example `package.json` file. ``` { "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" } } ``` In `peerDependencies`, use a caret (^) to specify the lowest version of `aws-cdk-lib` that your library works with. This maximizes the compatibility of your library with a range of CDK versions. Specify exact versions for alpha construct library modules, which have APIs that may change. Using `peerDependencies` makes sure that there is only one copy of all CDK libraries in the `node_modules` tree. In `devDependencies`, specify the tools and libraries you need for testing, optionally with ^ to indicate that later compatible versions are acceptable. Specify exactly (without ^ or \$1) the lowest versions of `aws-cdk-lib` and other CDK packages that you advertise your library be compatible with. This practice makes sure that your tests run against those versions. This way, if you inadvertently use a feature found only in newer versions, your tests can catch it. **Warning** `peerDependencies` are installed automatically only by NPM 7 and later. If you are using NPM 6 or earlier, or if you are using Yarn, you must include the dependencies of your dependencies in `devDependencies`. Otherwise, they won’t be installed, and you will receive a warning about unresolved peer dependencies. ### Installing and updating dependencies Run the following command to install your project’s dependencies. **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 ``` To update the installed modules, the preceding `npm install` and `yarn upgrade` commands can be used. Either command updates the packages in `node_modules` to the latest versions that satisfy the rules in `package.json`. However, they do not update `package.json` itself, which you might want to do to set a new minimum version. If you host your package on GitHub, you can configure [Dependabot version updates](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates) to automatically update `package.json`. Alternatively, use [npm-check-updates](https://www.npmjs.com/package/npm-check-updates). **Important** By design, when you install or update dependencies, NPM and Yarn choose the latest version of every package that satisfies the requirements specified in `package.json`. There is always a risk that these versions may be broken (either accidentally or intentionally). Test thoroughly after updating your project’s dependencies. ## AWS CDK idioms in TypeScript ### Props All AWS Construct Library classes are instantiated using three arguments: the *scope* in which the construct is being defined (its parent in the construct tree), an *id*, and *props*. Argument *props* is a bundle of key/value pairs that the construct uses to configure the AWS resources it creates. Other classes and methods also use the "bundle of attributes" pattern for arguments. In TypeScript, the shape of `props` is defined using an interface that tells you the required and optional arguments and their types. Such an interface is defined for each kind of `props` argument, usually specific to a single construct or method. For example, the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html) construct (in the `aws-cdk-lib/aws-s3` module) specifies a `props` argument conforming to the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html) interface. If a property is itself an object, for example the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html#websiteredirect](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html#websiteredirect) property of `BucketProps`, that object will have its own interface to which its shape must conform, in this case [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.RedirectTarget.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.RedirectTarget.html). If you are subclassing an AWS Construct Library class (or overriding a method that takes a props-like argument), you can inherit from the existing interface to create a new one that specifies any new props your code requires. When calling the parent class or base method, generally you can pass the entire props argument you received, since any attributes provided in the object but not specified in the interface will be ignored. A future release of the AWS CDK could coincidentally add a new property with a name you used for your own property. Passing the value you receive up the inheritance chain can then cause unexpected behavior. It’s safer to pass a shallow copy of the props you received with your property removed or set to `undefined`. For example: ``` super(scope, name, {...props, encryptionKeys: undefined}); ``` Alternatively, name your properties so that it is clear that they belong to your construct. This way, it is unlikely they will collide with properties in future AWS CDK releases. If there are many of them, use a single appropriately-named object to hold them. ### Missing values Missing values in an object (such as props) have the value `undefined` in TypeScript. Version 3.7 of the language introduced operators that simplify working with these values, making it easier to specify defaults and "short-circuit" chaining when an undefined value is reached. For more information about these features, see the [TypeScript 3.7 Release Notes](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html), specifically the first two features, Optional Chaining and Nullish Coalescing. ## Build and run CDK apps Generally, you should be in the project’s root directory when building and running your application. Node.js cannot run TypeScript directly; instead, your application is converted to JavaScript using the TypeScript compiler, `tsc`. The resulting JavaScript code is then executed. The AWS CDK automatically does this whenever it needs to run your app. However, it can be useful to compile manually to check for errors and to run tests. To compile your TypeScript app manually, issue `npm run build`. You may also issue `npm run watch` to enter watch mode, in which the TypeScript compiler automatically rebuilds your app whenever you save changes to a source file. # Working with the AWS CDK in JavaScript JavaScript is a fully-supported client language for the AWS CDK and is considered stable. Working with the AWS Cloud Development Kit (AWS CDK) in JavaScript uses familiar tools, including [Node.js](https://nodejs.org/) and the Node Package Manager (`npm`). You may also use [Yarn](https://yarnpkg.com/) if you prefer, though the examples in this Guide use NPM. The modules comprising the AWS Construct Library are distributed via the NPM repository, [npmjs.org](https://www.npmjs.com/). You can use any editor or IDE. Many AWS CDK developers use [Visual Studio Code](https://code.visualstudio.com/) (or its open-source equivalent [VSCodium](https://vscodium.com/)), which has good support for JavaScript. ## Get started with JavaScript To work with the AWS CDK, you must have an AWS account and credentials and have installed Node.js and the AWS CDK Toolkit. See [Getting started with the AWS CDK](getting-started.md). JavaScript AWS CDK applications require no additional prerequisites beyond these. **Note** Third-party language deprecation: language version is only supported until its EOL (End Of Life) shared by the vendor or community and is subject to change with prior notice. ## Creating a project You create a new AWS CDK project by invoking `cdk init` in an empty directory. Use the `--language` option and specify `javascript`: ``` $ mkdir my-project $ cd my-project $ cdk init app --language javascript ``` Creating a project also installs the [aws-cdk-lib](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib-readme.html) module and its dependencies. `cdk init` uses the name of the project folder to name various elements of the project, including classes, subfolders, and files. Hyphens in the folder name are converted to underscores. However, the name should otherwise follow the form of a JavaScript identifier; for example, it should not start with a number or contain spaces. ## Using local `cdk` For the most part, this guide assumes you install the CDK Toolkit globally (`npm install -g aws-cdk`), and the provided command examples (such as `cdk synth`) follow this assumption. This approach makes it easy to keep the CDK Toolkit up to date, and since the CDK takes a strict approach to backward compatibility, there is generally little risk in always using the latest version. Some teams prefer to specify all dependencies within each project, including tools like the CDK Toolkit. This practice lets you pin such components to specific versions and ensure that all developers on your team (and your CI/CD environment) use exactly those versions. This eliminates a possible source of change, helping to make builds and deployments more consistent and repeatable. The CDK includes a dependency for the CDK Toolkit in the JavaScript project template’s `package.json`, so if you want to use this approach, you don’t need to make any changes to your project. All you need to do is use slightly different commands for building your app and for issuing `cdk` commands. | Operation | Use global tools | Use local tools | | --- | --- | --- | | **Initialize project** | `cdk init --language javascript` | `npx aws-cdk init --language javascript` | | **Run CDK Toolkit command** | `cdk …​` | `npm run cdk …​` or `npx aws-cdk …​` | `npx aws-cdk` runs the version of the CDK Toolkit installed locally in the current project, if one exists, falling back to the global installation, if any. If no global installation exists, `npx` downloads a temporary copy of the CDK Toolkit and runs that. You may specify an arbitrary version of the CDK Toolkit using the `@` syntax: `npx aws-cdk@1.120 --version` prints `1.120.0`. **Tip** Set up an alias so you can use the `cdk` command with a local CDK Toolkit installation. ``` $ alias cdk="npx aws-cdk" ``` ``` doskey cdk=npx aws-cdk $* ``` ## Managing AWS Construct Library modules Use the Node Package Manager (`npm`) to install and update AWS Construct Library modules for use by your apps, as well as other packages you need. (You may use `yarn` instead of `npm` if you prefer.) `npm` also installs the dependencies for those modules automatically. Most AWS CDK constructs are in the main CDK package, named `aws-cdk-lib`, which is a default dependency in new projects created by `cdk init`. "Experimental" AWS Construct Library modules, where higher-level constructs are still under development, are named like `aws-cdk-lib/-alpha`. The service name has an *aws-* prefix. If you’re unsure of a module’s name, [search for it on NPM](https://www.npmjs.com/search?q=%40aws-cdk). **Note** The [CDK API Reference](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html) also shows the package names. For example, the command below installs the experimental module for AWS CodeStar. ``` npm install @aws-cdk/aws-codestar-alpha ``` Some services' Construct Library support is in more than one namespace. For example, besides `aws-route53`, there are three additional Amazon Route 53 namespaces, `aws-route53-targets`, `aws-route53-patterns`, and `aws-route53resolver`. Your project’s dependencies are maintained in `package.json`. You can edit this file to lock some or all of your dependencies to a specific version or to allow them to be updated to newer versions under certain criteria. To update your project’s NPM dependencies to the latest permitted version according to the rules you specified in `package.json`: ``` npm update ``` In JavaScript, you import modules into your code under the same name you use to install them using NPM. We recommend the following practices when importing AWS CDK classes and AWS Construct Library modules in your applications. Following these guidelines will help make your code consistent with other AWS CDK applications as well as easier to understand. + Use `require()`, not ES6-style `import` directives. Older versions of Node.js do not support ES6 imports, so using the older syntax is more widely compatible. (If you really want to use ES6 imports, use [esm](https://www.npmjs.com/package/esm) to ensure your project is compatible with all supported versions of Node.js.) + Generally, import individual classes from `aws-cdk-lib`. ``` const { App, Stack } = require('aws-cdk-lib'); ``` + If you need many classes from `aws-cdk-lib`, you may use a namespace alias of `cdk` instead of importing the individual classes. Avoid doing both. ``` const cdk = require('aws-cdk-lib'); ``` + Generally, import AWS Construct Libraries using short namespace aliases. ``` const { s3 } = require('aws-cdk-lib/aws-s3'); ``` ## Managing dependencies in JavaScript In JavaScript CDK projects, dependencies are specified in the `package.json` file in the project’s main directory. The core AWS CDK modules are in a single `NPM` package called `aws-cdk-lib`. When you install a package using `npm install`, NPM records the package in `package.json` for you. If you prefer, you may use Yarn in place of NPM. However, the CDK does not support Yarn’s plug-and-play mode, which is default mode in Yarn 2. Add the following to your project’s `.yarnrc.yml` file to turn off this feature. ``` nodeLinker: node-modules ``` ### CDK applications The following is an example `package.json` file generated by the `cdk init --language typescript` command. The file generated for JavaScript is similar, only without the TypeScript-related entries. ``` { "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" } } ``` For deployable CDK apps, `aws-cdk-lib` must be specified in the `dependencies` section of `package.json`. You can use a caret (^) version number specifier to indicate that you will accept later versions than the one specified as long as they are within the same major version. For experimental constructs, specify exact versions for the alpha construct library modules, which have APIs that may change. Do not use ^ or \$1 since later versions of these modules may bring API changes that can break your app. Specify versions of libraries and tools needed to test your app (for example, the `jest` testing framework) in the `devDependencies` section of `package.json`. Optionally, use ^ to specify that later compatible versions are acceptable. ### Third-party construct libraries If you’re developing a construct library, specify its dependencies using a combination of the `peerDependencies` and `devDependencies` sections, as shown in the following example `package.json` file. ``` { "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" } } ``` In `peerDependencies`, use a caret (^) to specify the lowest version of `aws-cdk-lib` that your library works with. This maximizes the compatibility of your library with a range of CDK versions. Specify exact versions for alpha construct library modules, which have APIs that may change. Using `peerDependencies` makes sure that there is only one copy of all CDK libraries in the `node_modules` tree. In `devDependencies`, specify the tools and libraries you need for testing, optionally with ^ to indicate that later compatible versions are acceptable. Specify exactly (without ^ or \$1) the lowest versions of `aws-cdk-lib` and other CDK packages that you advertise your library be compatible with. This practice makes sure that your tests run against those versions. This way, if you inadvertently use a feature found only in newer versions, your tests can catch it. **Warning** `peerDependencies` are installed automatically only by NPM 7 and later. If you are using NPM 6 or earlier, or if you are using Yarn, you must include the dependencies of your dependencies in `devDependencies`. Otherwise, they won’t be installed, and you will receive a warning about unresolved peer dependencies. ### Installing and updating dependencies Run the following command to install your project’s dependencies. **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 ``` To update the installed modules, the preceding `npm install` and `yarn upgrade` commands can be used. Either command updates the packages in `node_modules` to the latest versions that satisfy the rules in `package.json`. However, they do not update `package.json` itself, which you might want to do to set a new minimum version. If you host your package on GitHub, you can configure [Dependabot version updates](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates) to automatically update `package.json`. Alternatively, use [npm-check-updates](https://www.npmjs.com/package/npm-check-updates). **Important** By design, when you install or update dependencies, NPM and Yarn choose the latest version of every package that satisfies the requirements specified in `package.json`. There is always a risk that these versions may be broken (either accidentally or intentionally). Test thoroughly after updating your project’s dependencies. ## AWS CDK idioms in JavaScript ### Props All AWS Construct Library classes are instantiated using three arguments: the *scope* in which the construct is being defined (its parent in the construct tree), an *id*, and *props*, a bundle of key/value pairs that the construct uses to configure the AWS resources it creates. Other classes and methods also use the "bundle of attributes" pattern for arguments. Using an IDE or editor that has good JavaScript autocomplete will help avoid misspelling property names. If a construct is expecting an `encryptionKeys` property, and you spell it `encryptionkeys`, when instantiating the construct, you haven’t passed the value you intended. This can cause an error at synthesis time if the property is required, or cause the property to be silently ignored if it is optional. In the latter case, you may get a default behavior you intended to override. Take special care here. When subclassing an AWS Construct Library class (or overriding a method that takes a props-like argument), you may want to accept additional properties for your own use. These values will be ignored by the parent class or overridden method, because they are never accessed in that code, so you can generally pass on all the props you received. A future release of the AWS CDK could coincidentally add a new property with a name you used for your own property. Passing the value you receive up the inheritance chain can then cause unexpected behavior. It’s safer to pass a shallow copy of the props you received with your property removed or set to `undefined`. For example: ``` super(scope, name, {...props, encryptionKeys: undefined}); ``` Alternatively, name your properties so that it is clear that they belong to your construct. This way, it is unlikely they will collide with properties in future AWS CDK releases. If there are many of them, use a single appropriately-named object to hold them. ### Missing values Missing values in an object (such as `props`) have the value `undefined` in JavaScript. The usual techniques apply for dealing with these. For example, a common idiom for accessing a property of a value that may be undefined is as follows: ``` // 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; ``` However, if `a` could have some other "falsy" value besides `undefined`, it is better to make the test more explicit. Here, we’ll take advantage of the fact that `null` and `undefined` are equal to test for them both at once: ``` let c = a == null ? a : a.b; ``` **Tip** Node.js 14.0 and later support new operators that can simplify the handling of undefined values. For more information, see the [optional chaining](https://github.com/tc39/proposal-optional-chaining/blob/master/README.md) and [nullish coalescing](https://github.com/tc39/proposal-nullish-coalescing/blob/master/README.md) proposals. ## Using TypeScript examples with JavaScript [TypeScript](https://www.typescriptlang.org/) is the language we use to develop the AWS CDK, and it was the first language supported for developing applications, so many available AWS CDK code examples are written in TypeScript. These code examples can be a good resource for JavaScript developers; you just need to remove the TypeScript-specific parts of the code. TypeScript snippets often use the newer ECMAScript `import` and `export` keywords to import objects from other modules and to declare the objects to be made available outside the current module. Node.js has just begun supporting these keywords in its latest releases. Depending on the version of Node.js you’re using (or wish to support), you might rewrite imports and exports to use the older syntax. Imports can be replaced with calls to the `require()` function. **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'); ``` Exports can be assigned to the `module.exports` object. **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 } ``` **Note** An alternative to using the old-style imports and exports is to use the [esm](https://www.npmjs.com/package/esm) module. Once you’ve got the imports and exports sorted, you can dig into the actual code. You may run into these commonly-used TypeScript features: + Type annotations + Interface definitions + Type conversions/casts + Access modifiers Type annotations may be provided for variables, class members, function parameters, and function return types. For variables, parameters, and members, types are specified by following the identifier with a colon and the type. Function return values follow the function signature and consist of a colon and the type. To convert type-annotated code to JavaScript, remove the colon and the type. Class members must have some value in JavaScript; set them to `undefined` if they only have a type annotation in TypeScript. **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) { // ... } ``` In TypeScript, interfaces are used to give bundles of required and optional properties, and their types, a name. You can then use the interface name as a type annotation. TypeScript will make sure that the object you use as, for example, an argument to a function has the required properties of the right types. ``` interface myFuncProps { code: lambda.Code, handler?: string } ``` JavaScript does not have an interface feature, so once you’ve removed the type annotations, delete the interface declarations entirely. When a function or method returns a general-purpose type (such as `object`), but you want to treat that value as a more specific child type to access properties or methods that are not part of the more general type’s interface, TypeScript lets you *cast* the value using `as` followed by a type or interface name. JavaScript doesn’t support (or need) this, so simply remove `as` and the following identifier. A less-common cast syntax is to use a type name in brackets, ``; these casts, too, must be removed. Finally, TypeScript supports the access modifiers `public`, `protected`, and `private` for members of classes. All class members in JavaScript are public. Simply remove these modifiers wherever you see them. Knowing how to identify and remove these TypeScript features goes a long way toward adapting short TypeScript snippets to JavaScript. But it may be impractical to convert longer TypeScript examples in this fashion, since they are more likely to use other TypeScript features. For these situations, we recommend [Sucrase](https://github.com/alangpierce/sucrase). Sucrase won’t complain if code uses an undefined variable, for example, as `tsc` would. If it is syntactically valid, then with few exceptions, Sucrase can translate it to JavaScript. This makes it particularly valuable for converting snippets that may not be runnable on their own. ## Migrating to TypeScript Many JavaScript developers move to [TypeScript](https://www.typescriptlang.org/) as their projects get larger and more complex. TypeScript is a superset of JavaScript—​all JavaScript code is valid TypeScript code, so no changes to your code are required—​and it is also a supported AWS CDK language. Type annotations and other TypeScript features are optional and can be added to your AWS CDK app as you find value in them. TypeScript also gives you early access to new JavaScript features, such as optional chaining and nullish coalescing, before they’re finalized—​and without requiring that you upgrade Node.js. TypeScript’s "shape-based" interfaces, which define bundles of required and optional properties (and their types) within an object, allow common mistakes to be caught while you’re writing the code, and make it easier for your IDE to provide robust autocomplete and other real-time coding advice. Coding in TypeScript does involve an additional step: compiling your app with the TypeScript compiler, `tsc`. For typical AWS CDK apps, compilation requires a few seconds at most. The easiest way to migrate an existing JavaScript AWS CDK app to TypeScript is to create a new TypeScript project using `cdk init app --language typescript`, then copy your source files (and any other necessary files, such as assets like AWS Lambda function source code) to the new project. Rename your JavaScript files to end in `.ts` and begin developing in TypeScript. # Working with the AWS CDK in Python Python is a fully-supported client language for the AWS Cloud Development Kit (AWS CDK) and is considered stable. Working with the AWS CDK in Python uses familiar tools, including the standard Python implementation (CPython), virtual environments with `virtualenv`, and the Python package installer `pip`. The modules comprising the AWS Construct Library are distributed via [pypi.org](https://pypi.org/search/?q=aws-cdk). The Python version of the AWS CDK even uses Python-style identifiers (for example, `snake_case` method names). You can use any editor or IDE. Many AWS CDK developers use [Visual Studio Code](https://code.visualstudio.com/) (or its open-source equivalent [VSCodium](https://vscodium.com/)), which has good support for Python via an [official extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python). The IDLE editor included with Python will suffice to get started. The Python modules for the AWS CDK do have type hints, which are useful for a linting tool or an IDE that supports type validation. ## Get started with Python To work with the AWS CDK, you must have an AWS account and credentials and have installed Node.js and the AWS CDK Toolkit. See [Getting started with the AWS CDK](getting-started.md). Python AWS CDK applications require Python 3.9 or later. If you don’t already have it installed, [download a compatible version](https://www.python.org/downloads/) for your operating system at [python.org](https://www.python.org/). If you run Linux, your system may have come with a compatible version, or you may install it using your distro’s package manager (`yum`, `apt`, etc.). Mac users may be interested in [Homebrew](https://brew.sh/), a Linux-style package manager for macOS. **Note** Third-party language deprecation: language version is only supported until its EOL (End Of Life) shared by the vendor or community and is subject to change with prior notice. The Python package installer, `pip`, and virtual environment manager, `virtualenv`, are also required. Windows installations of compatible Python versions include these tools. On Linux, `pip` and `virtualenv` may be provided as separate packages in your package manager. Alternatively, you may install them with the following commands: ``` python -m ensurepip --upgrade python -m pip install --upgrade pip python -m pip install --upgrade virtualenv ``` If you encounter a permission error, run the above commands with the `--user` flag so that the modules are installed in your user directory, or use `sudo` to obtain the permissions to install the modules system-wide. **Note** It is common for Linux distros to use the executable name `python3` for Python 3.x, and have `python` refer to a Python 2.x installation. Some distros have an optional package you can install that makes the `python` command refer to Python 3. Failing that, you can adjust the command used to run your application by editing `cdk.json` in the project’s main directory. **Note** On Windows, you may want to invoke Python (and `pip`) using the `py` executable, the [Python launcher for Windows](https://docs.python.org/3/using/windows.html#launcher). Among other things, the launcher allows you to easily specify which installed version of Python you want to use. If typing `python` at the command line results in a message about installing Python from the Windows Store, even after installing a Windows version of Python, open Windows' Manage App Execution Aliases settings panel and turn off the two App Installer entries for Python. ## Creating a project You create a new AWS CDK project by invoking `cdk init` in an empty directory. Use the `--language` option and specify `python`: ``` $ mkdir my-project $ cd my-project $ cdk init app --language python ``` `cdk init` uses the name of the project folder to name various elements of the project, including classes, subfolders, and files. Hyphens in the folder name are converted to underscores. However, the name should otherwise follow the form of a Python identifier; for example, it should not start with a number or contain spaces. To work with the new project, activate its virtual environment. This allows the project’s dependencies to be installed locally in the project folder, instead of globally. ``` $ source .venv/bin/activate ``` **Note** You may recognize this as the Mac/Linux command to activate a virtual environment. The Python templates include a batch file, `source.bat`, that allows the same command to be used on Windows. The traditional Windows command, `.\venv\Scripts\activate`, works, too. If you initialized your AWS CDK project using CDK Toolkit v1.70.0 or earlier, your virtual environment is in the `.env` directory instead of `.venv`. **Important** Activate the project’s virtual environment whenever you start working on it. Otherwise, you won’t have access to the modules installed there, and modules you install will go in the Python global module directory (or will result in a permission error). After activating your virtual environment for the first time, install the app’s standard dependencies: ``` $ python -m pip install -r requirements.txt ``` ## Managing AWS Construct Library modules Use the Python package installer, `pip`, to install and update AWS Construct Library modules for use by your apps, as well as other packages you need. `pip` also installs the dependencies for those modules automatically. If your system does not recognize `pip` as a standalone command, invoke `pip` as a Python module, like this: ``` $ python -m pip ``` Most AWS CDK constructs are in `aws-cdk-lib`. Experimental modules are in separate modules named like `aws-cdk..alpha`. The service name includes an *aws* prefix. If you’re unsure of a module’s name, [search for it at PyPI](https://pypi.org/search/?q=aws-cdk). For example, the command below installs the AWS CodeStar library. ``` $ python -m pip install aws-cdk.aws-codestar-alpha ``` Some services' constructs are in more than one namespace. For example, besides `aws-cdk.aws-route53`, there are three additional Amazon Route 53 namespaces, named `aws-route53-targets`, `aws-route53-patterns`, and `aws-route53resolver`. **Note** The [Python edition of the CDK API Reference](https://docs.aws.amazon.com/cdk/api/v2/python/index.html) also shows the package names. The names used for importing AWS Construct Library modules into your Python code look like the following. ``` import aws_cdk.aws_s3 as s3 import aws_cdk.aws_lambda as lambda_ ``` We recommend the following practices when importing AWS CDK classes and AWS Construct Library modules in your applications. Following these guidelines will help make your code consistent with other AWS CDK applications as well as easier to understand. + Generally, import individual classes from top-level `aws_cdk`. ``` from aws_cdk import App, Construct ``` + If you need many classes from the `aws_cdk`, you may use a namespace alias of `cdk` instead of importing individual classes. Avoid doing both. ``` import aws_cdk as cdk ``` + Generally, import AWS Construct Libraries using short namespace aliases. ``` import aws_cdk.aws_s3 as s3 ``` After installing a module, update your project’s `requirements.txt` file, which lists your project’s dependencies. It is best to do this manually rather than using `pip freeze`. `pip freeze` captures the current versions of all modules installed in your Python virtual environment, which can be useful when bundling up a project to be run elsewhere. Usually, though, your `requirements.txt` should list only top-level dependencies (modules that your app depends on directly) and not the dependencies of those libraries. This strategy makes updating your dependencies simpler. You can edit `requirements.txt` to allow upgrades; simply replace the `==` preceding a version number with `~=` to allow upgrades to a higher compatible version, or remove the version requirement entirely to specify the latest available version of the module. With `requirements.txt` edited appropriately to allow upgrades, issue this command to upgrade your project’s installed modules at any time: ``` $ pip install --upgrade -r requirements.txt ``` ## Managing dependencies in Python In Python, you specify dependencies by putting them in `requirements.txt` for applications or `setup.py` for construct libraries. Dependencies are then managed with the PIP tool. PIP is invoked in one of the following ways: ``` pip python -m pip ``` The `python -m pip` invocation works on most systems; `pip` requires that PIP’s executable be on the system path. If `pip` doesn’t work, try replacing it with `python -m pip`. The `cdk init --language python` command creates a virtual environment for your new project. This lets each project have its own versions of dependencies, and also a basic `requirements.txt` file. You must activate this virtual environment by running `source .venv/bin/activate` each time you begin working with the project. On Windows, run `.\venv\Scripts\activate` instead ### CDK applications The following is an example `requirements.txt` file. Because PIP does not have a dependency-locking feature, we recommend that you use the == operator to specify exact versions for all dependencies, as shown here. ``` aws-cdk-lib==2.14.0 aws-cdk.aws-appsync-alpha==2.10.0a0 ``` Installing a module with `pip install` does not automatically add it to `requirements.txt`. You must do that yourself. If you want to upgrade to a later version of a dependency, edit its version number in `requirements.txt`. To install or update your project’s dependencies after creating or editing `requirements.txt`, run the following: ``` python -m pip install -r requirements.txt ``` **Tip** The `pip freeze` command outputs the versions of all installed dependencies in a format that can be written to a text file. This can be used as a requirements file with `pip install -r`. This file is convenient for pinning all dependencies (including transitive ones) to the exact versions that you tested with. To avoid problems when upgrading packages later, use a separate file for this, such as `freeze.txt` (not `requirements.txt`). Then, regenerate it when you upgrade your project’s dependencies. ### Third-party construct libraries In libraries, dependencies are specified in `setup.py`, so that transitive dependencies are automatically downloaded when the package is consumed by an application. Otherwise, every application that wants to use your package needs to copy your dependencies into their `requirements.txt`. An example `setup.py` is shown here. ``` from setuptools import setup setup( name='my-package', version='0.0.1', install_requires=[ 'aws-cdk-lib==2.14.0', ], ... ) ``` To work on the package for development, create or activate a virtual environment, then run the following command. ``` python -m pip install -e . ``` Although PIP automatically installs transitive dependencies, there can only be one installed copy of any one package. The version that is specified highest in the dependency tree is selected; applications always have the last word in what version of packages get installed. ## AWS CDK idioms in Python ### Language conflicts In Python, `lambda` is a language keyword, so you cannot use it as a name for the AWS Lambda construct library module or Lambda functions. The Python convention for such conflicts is to use a trailing underscore, as in `lambda_`, in the variable name. By convention, the second argument to AWS CDK constructs is named `id`. When writing your own stacks and constructs, calling a parameter `id` "shadows" the Python built-in function `id()`, which returns an object’s unique identifier. This function isn’t used very often, but if you should happen to need it in your construct, rename the argument, for example `construct_id`. ### Arguments and properties All AWS Construct Library classes are instantiated using three arguments: the *scope* in which the construct is being defined (its parent in the construct tree), an *id*, and *props*, a bundle of key/value pairs that the construct uses to configure the resources it creates. Other classes and methods also use the "bundle of attributes" pattern for arguments. *scope* and *id* should always be passed as positional arguments, not keyword arguments, because their names change if the construct accepts a property named *scope* or *id*. In Python, props are expressed as keyword arguments. If an argument contains nested data structures, these are expressed using a class which takes its own keyword arguments at instantiation. The same pattern is applied to other method calls that take a structured argument. For example, in a Amazon S3 bucket’s `add_lifecycle_rule` method, the `transitions` property is a list of `Transition` instances. ``` bucket.add_lifecycle_rule( transitions=[ Transition( storage_class=StorageClass.GLACIER, transition_after=Duration.days(10) ) ] ) ``` When extending a class or overriding a method, you may want to accept additional arguments for your own purposes that are not understood by the parent class. In this case you should accept the arguments you don’t care about using the \$1\$1kwargs idiom, and use keyword-only arguments to accept the arguments you’re interested in. When calling the parent’s constructor or the overridden method, pass only the arguments it is expecting (often just \$1\$1kwargs). Passing arguments that the parent class or method doesn’t expect results in an error. ``` class MyConstruct(Construct): def __init__(self, id, *, MyProperty=42, **kwargs): super().__init__(self, id, **kwargs) # ... ``` A future release of the AWS CDK could coincidentally add a new property with a name you used for your own property. This won’t cause any technical issues for users of your construct or method (since your property isn’t passed "up the chain," the parent class or overridden method will simply use a default value) but it may cause confusion. You can avoid this potential problem by naming your properties so they clearly belong to your construct. If there are many new properties, bundle them into an appropriately-named class and pass it as a single keyword argument. ### Missing values The AWS CDK uses `None` to represent missing or undefined values. When working with \$1\$1kwargs, use the dictionary’s `get()` method to provide a default value if a property is not provided. Avoid using `kwargs[…​]`, as this raises `KeyError` for missing values. ``` encrypted = kwargs.get("encrypted") # None if no property "encrypted" exists encrypted = kwargs.get("encrypted", False) # specify default of False if property is missing ``` Some AWS CDK methods (such as `tryGetContext()` to get a runtime context value) may return `None`, which you will need to check explicitly. ### Using interfaces Python doesn’t have an interface feature as some other languages do, though it does have [abstract base classes](https://docs.python.org/3/library/abc.html), which are similar. (If you’re not familiar with interfaces, Wikipedia has [a good introduction](https://en.wikipedia.org/wiki/Interface_(computing)#In_object-oriented_languages).) TypeScript, the language in which the AWS CDK is implemented, does provide interfaces, and constructs and other AWS CDK objects often require an object that adheres to a particular interface, rather than inheriting from a particular class. So the AWS CDK provides its own interface feature as part of the [JSII](https://github.com/aws/jsii) layer. To indicate that a class implements a particular interface, you can use the `@jsii.implements` decorator: ``` from aws_cdk import IAspect, IConstruct import jsii @jsii.implements(IAspect) class MyAspect(): def visit(self, node: IConstruct) -> None: print("Visited", node.node.path) ``` ### Type pitfalls Python uses dynamic typing, where all variables may refer to a value of any type. Parameters and return values may be annotated with types, but these are "hints" and are not enforced. This means that in Python, it is easy to pass the incorrect type of value to a AWS CDK construct. Instead of getting a type error during build, as you would from a statically-typed language, you may instead get a runtime error when the JSII layer (which translates between Python and the AWS CDK’s TypeScript core) is unable to deal with the unexpected type. In our experience, the type errors Python programmers make tend to fall into these categories. + Passing a single value where a construct expects a container (Python list or dictionary) or vice versa. + Passing a value of a type associated with a layer 1 (`CfnXxxxxx`) construct to a L2 or L3 construct, or vice versa. ## Preventing type errors The AWS CDK Python modules include type annotations, so you can use tools that support them to catch type errors before deployment. ### IDE integration (recommended) Visual Studio Code with Pylance provides real-time type checking as you write code: 1. Install the [Pylance extension](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance) 1. Configure strict type checking in `.vscode/settings.json`: ``` { "python.languageServer": "Pylance", "python.analysis.typeCheckingMode": "strict" } ``` 1. Type errors now appear immediately with red squiggles and detailed error messages [PyCharm](https://www.jetbrains.com/pycharm/) also provides built-in type checking with similar capabilities. ### Command-line type checking For CI/CD pipelines or pre-commit validation, use one of these type checkers: **MyPy (Python-based):** ``` pip install mypy mypy app.py ``` **Pyright (faster, JavaScript-based, same engine as Pylance):** ``` npm install -g pyright pyright app.py ``` ### Recommended workflow 1. During development: Use Pyright or Pylance for instant feedback 1. Before commit: Run `mypy app.py` or `pyright app.py` 1. In CI/CD: Make type checking a required step before deployment # Working with the AWS CDK in Java Java is a fully-supported client language for the AWS CDK and is considered stable. You can develop AWS CDK applications in Java using familiar tools, including the JDK (Oracle’s, or an OpenJDK distribution such as Amazon Corretto) and Apache Maven. The AWS CDK supports Java 8 and later. We recommend using the latest version you can, however, because later versions of the language include improvements that are particularly convenient for developing AWS CDK applications. For example, Java 9 introduces the `Map.of()` method (a convenient way to declare hashmaps that would be written as object literals in TypeScript). Java 10 introduces local type inference using the `var` keyword. **Note** Most code examples in this Developer Guide work with Java 8. A few examples use `Map.of()`; these examples include comments noting that they require Java 9. You can use any text editor, or a Java IDE that can read Maven projects, to work on your AWS CDK apps. We provide [Eclipse](https://www.eclipse.org/downloads/) hints in this Guide, but IntelliJ IDEA, NetBeans, and other IDEs can import Maven projects and can be used for developing AWS CDK applications in Java. It is possible to write AWS CDK applications in JVM-hosted languages other than Java (for example, Kotlin, Groovy, Clojure, or Scala), but the experience may not be particularly idiomatic, and we are unable to provide any support for these languages. ## Get started with Java To work with the AWS CDK, you must have an AWS account and credentials and have installed Node.js and the AWS CDK Toolkit. See [Getting started with the AWS CDK](getting-started.md). Java AWS CDK applications require Java 8 (v1.8) or later. We recommend [Amazon Corretto](https://aws.amazon.com/corretto/), but you can use any OpenJDK distribution or [Oracle’s JDK](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html). You will also need [Apache Maven](https://maven.apache.org/download.cgi) 3.5 or later. You can also use tools such as Gradle, but the application skeletons generated by the AWS CDK Toolkit are Maven projects. **Note** Third-party language deprecation: language version is only supported until its EOL (End Of Life) shared by the vendor or community and is subject to change with prior notice. ## Creating a project You create a new AWS CDK project by invoking `cdk init` in an empty directory. Use the `--language` option and specify `java`: ``` $ mkdir my-project $ cd my-project $ cdk init app --language java ``` `cdk init` uses the name of the project folder to name various elements of the project, including classes, subfolders, and files. Hyphens in the folder name are converted to underscores. However, the name should otherwise follow the form of a Java identifier; for example, it should not start with a number or contain spaces. The resulting project includes a reference to the `software.amazon.awscdk` Maven package. It and its dependencies are automatically installed by Maven. If you are using an IDE, you can now open or import the project. In Eclipse, for example, choose **File** > **Import** > **Maven** > **Existing Maven Projects**. Make sure that the project settings are set to use Java 8 (1.8). ## Managing AWS Construct Library modules Use Maven to install AWS Construct Library packages, which are in the group `software.amazon.awscdk`. Most constructs are in the artifact `aws-cdk-lib`, which is added to new Java projects by default. Modules for services whose higher-level CDK support is still being developed are in separate "experimental" packages, named with a short version (no AWS or Amazon prefix) of their service’s name. [Search the Maven Central Repository](https://search.maven.org/search?q=software.amazon.awscdk) to find the names of all AWS CDK and AWS Construct Module libraries. **Note** The [Java edition of the CDK API Reference](https://docs.aws.amazon.com/cdk/api/v2/java/index.html) also shows the package names. Some services' AWS Construct Library support is in more than one namespace. For example, Amazon Route 53 has its functionality divided into `software.amazon.awscdk.route53`, `route53-patterns`, `route53resolver`, and `route53-targets`. The main AWS CDK package is imported in Java code as `software.amazon.awscdk`. Modules for the various services in the AWS Construct Library live under `software.amazon.awscdk.services` and are named similarly to their Maven package name. For example, the Amazon S3 module’s namespace is `software.amazon.awscdk.services.s3`. We recommend writing a separate Java `import` statement for each AWS Construct Library class you use in each of your Java source files, and avoiding wildcard imports. You can always use a type’s fully-qualified name (including its namespace) without an `import` statement. If your application depends on an experimental package, edit your project’s `pom.xml` and add a new `` element in the `` container. For example, the following `` element specifies the CodeStar experimental construct library module: ``` software.amazon.awscdk codestar-alpha 2.0.0-alpha.10 ``` **Tip** If you use a Java IDE, it probably has features for managing Maven dependencies. We recommend editing `pom.xml` directly, however, unless you are absolutely sure the IDE’s functionality matches what you’d do by hand. ## Managing dependencies in Java In Java, dependencies are specified in `pom.xml` and installed using Maven. The `` container includes a `` element for each package. Following is a section of `pom.xml` for a typical CDK Java app. ``` software.amazon.awscdk aws-cdk-lib 2.14.0 software.amazon.awscdk appsync-alpha 2.10.0-alpha.0 ``` **Tip** Many Java IDEs have integrated Maven support and visual `pom.xml` editors, which you may find convenient for managing dependencies. Maven does not support dependency locking. Although it’s possible to specify version ranges in `pom.xml`, we recommend you always use exact versions to keep your builds repeatable. Maven automatically installs transitive dependencies, but there can only be one installed copy of each package. The version that is specified highest in the POM tree is selected; applications always have the last word in what version of packages get installed. Maven automatically installs or updates your dependencies whenever you build (`mvn compile`) or package (`mvn package`) your project. The CDK Toolkit does this automatically every time you run it, so generally there is no need to manually invoke Maven. ## AWS CDK idioms in Java ### Props All AWS Construct Library classes are instantiated using three arguments: the *scope* in which the construct is being defined (its parent in the construct tree), an *id*, and *props*, a bundle of key/value pairs that the construct uses to configure the resources it creates. Other classes and methods also use the "bundle of attributes" pattern for arguments. In Java, props are expressed using the [Builder pattern](https://en.wikipedia.org/wiki/Builder_pattern). Each construct type has a corresponding props type; for example, the `Bucket` construct (which represents an Amazon S3 bucket) takes as its props an instance of `BucketProps`. The `BucketProps` class (like every AWS Construct Library props class) has an inner class called `Builder`. The `BucketProps.Builder` type offers methods to set the various properties of a `BucketProps` instance. Each method returns the `Builder` instance, so the method calls can be chained to set multiple properties. At the end of the chain, you call `build()` to actually produce the `BucketProps` object. ``` Bucket bucket = new Bucket(this, "amzn-s3-demo-bucket", new BucketProps.Builder() .versioned(true) .encryption(BucketEncryption.KMS_MANAGED) .build()); ``` Constructs, and other classes that take a props-like object as their final argument, offer a shortcut. The class has a `Builder` of its own that instantiates it and its props object in one step. This way, you don’t need to explicitly instantiate (for example) both `BucketProps` and a `Bucket`--and you don’t need an import for the props type. ``` Bucket bucket = Bucket.Builder.create(this, "amzn-s3-demo-bucket") .versioned(true) .encryption(BucketEncryption.KMS_MANAGED) .build(); ``` When deriving your own construct from an existing construct, you may want to accept additional properties. We recommend that you follow these builder patterns. However, this isn’t as simple as subclassing a construct class. You must provide the moving parts of the two new `Builder` classes yourself. You may prefer to simply have your construct accept one or more additional arguments. You should provide additional constructors when an argument is optional. ### Generic structures In some APIs, the AWS CDK uses JavaScript arrays or untyped objects as input to a method. (See, for example, AWS CodeBuild’s [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_codebuild.BuildSpec.html#static-fromwbrobjectvalue](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_codebuild.BuildSpec.html#static-fromwbrobjectvalue) method.) In Java, these objects are represented as `java.util.Map`. In cases where the values are all strings, you can use `Map`. Java does not provide a way to write literals for such containers like some other languages do. In Java 9 and later, you can use [https://docs.oracle.com/javase/9/docs/api/java/util/Map.html#ofEntries-java.util.Map.Entry…​-](https://docs.oracle.com/javase/9/docs/api/java/util/Map.html#ofEntries-java.util.Map.Entry…​-) to conveniently define maps of up to ten entries inline with one of these calls. ``` java.util.Map.of( "base-directory", "dist", "files", "LambdaStack.template.json" ) ``` To create maps with more than ten entries, use [https://docs.oracle.com/javase/9/docs/api/java/util/Map.html#ofEntries-java.util.Map.Entry…​-](https://docs.oracle.com/javase/9/docs/api/java/util/Map.html#ofEntries-java.util.Map.Entry…​-). If you are using Java 8, you could provide your own methods similar to to these. JavaScript arrays are represented as `List` or `List` in Java. The method `java.util.Arrays.asList` is convenient for defining short `List`s. ``` List cmds = Arrays.asList("cd lambda", "npm install", "npm install typescript") ``` ### Missing values In Java, missing values in AWS CDK objects such as props are represented by `null`. You must explicitly test any value that could be `null` to make sure it contains a value before doing anything with it. Java does not have "syntactic sugar" to help handle null values as some other languages do. You may find Apache ObjectUtil’s [https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/ObjectUtils.html#defaultIfNull-T-T-](https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/ObjectUtils.html#defaultIfNull-T-T-) and [https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/ObjectUtils.html#firstNonNull-T…​-](https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/ObjectUtils.html#firstNonNull-T…​-) useful in some situations. Alternatively, write your own static helper methods to make it easier to handle potentially null values and make your code more readable. ## Build and run CDK applications The AWS CDK automatically compiles your app before running it. However, it can be useful to build your app manually to check for errors and to run tests. You can do this in your IDE (for example, press Control-B in Eclipse) or by issuing `mvn compile` at a command prompt while in your project’s root directory. Run any tests you’ve written by running `mvn test` at a command prompt. # Working with the AWS CDK in C\$1 .NET is a fully-supported client language for the AWS CDK and is considered stable. C\$1 is the main .NET language for which we provide examples and support. You can choose to write AWS CDK applications in other .NET languages, such as Visual Basic or F\$1, but AWS offers limited support for using these languages with the CDK. You can develop AWS CDK applications in C\$1 using familiar tools including Visual Studio, Visual Studio Code, the `dotnet` command, and the NuGet package manager. The modules comprising the AWS Construct Library are distributed via [nuget.org](https://www.nuget.org/packages?q=amazon.cdk.aws). We suggest using [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) (any edition) on Windows to develop AWS CDK apps in C\$1. ## Get started with C\$1 To work with the AWS CDK, you must have an AWS account and credentials and have installed Node.js and the AWS CDK Toolkit. See [Getting started with the AWS CDK](getting-started.md). C\$1 AWS CDK applications require .NET 8.0 or later, available [here](https://dotnet.microsoft.com/en-us/download/dotnet). **Note** Third-party language deprecation: language version is only supported until its EOL (End Of Life) shared by the vendor or community and is subject to change with prior notice. The .NET toolchain includes `dotnet`, a command-line tool for building and running .NET applications and managing NuGet packages. Even if you work mainly in Visual Studio, this command can be useful for batch operations and for installing AWS Construct Library packages. ## Creating a project You create a new AWS CDK project by invoking `cdk init` in an empty directory. Use the `--language` option and specify `csharp`: ``` mkdir my-project cd my-project cdk init app --language csharp ``` `cdk init` uses the name of the project folder to name various elements of the project, including classes, subfolders, and files. Hyphens in the folder name are converted to underscores. However, the name should otherwise follow the form of a C\$1 identifier; for example, it should not start with a number or contain spaces. The resulting project includes a reference to the `Amazon.CDK.Lib` NuGet package. It and its dependencies are installed automatically by NuGet. ## Managing AWS Construct Library modules The .NET ecosystem uses the NuGet package manager. The main CDK package, which contains the core classes and all stable service constructs, is `Amazon.CDK.Lib`. Experimental modules, where new functionality is under active development, are named like `Amazon.CDK.AWS..Alpha`, where the service name is a short name without an AWS or Amazon prefix. For example, the NuGet package name for the AWS IoT module is `Amazon.CDK.AWS.IoT.Alpha`. If you can’t find a package you want, [search Nuget.org](https://www.nuget.org/packages?q=amazon.cdk.aws). **Note** The [.NET edition of the CDK API Reference](https://docs.aws.amazon.com/cdk/api/latest/dotnet/api/index.html) also shows the package names. Some services' AWS Construct Library support is in more than one module. For example, AWS IoT has a second module named `Amazon.CDK.AWS.IoT.Actions.Alpha`. The AWS CDK’s main module, which you’ll need in most AWS CDK apps, is imported in C\$1 code as `Amazon.CDK`. Modules for the various services in the AWS Construct Library live under `Amazon.CDK.AWS `. For example, the Amazon S3 module’s namespace is `Amazon.CDK.AWS.S3`. We recommend writing C\$1 `using` directives for the CDK core constructs and for each AWS service you use in each of your C\$1 source files. You may find it convenient to use an alias for a namespace or type to help resolve name conflicts. You can always use a type’s fully-qualified name (including its namespace) without a `using` statement. ## Managing dependencies in C\$1 In C\$1 AWS CDK apps, you manage dependencies using NuGet. NuGet has four standard, mostly equivalent interfaces. Use the one that suits your needs and working style. You can also use compatible tools, such as [Paket](https://fsprojects.github.io/Paket/) or [MyGet](https://www.myget.org/) or even edit the `.csproj` file directly. NuGet does not let you specify version ranges for dependencies. Every dependency is pinned to a specific version. After updating your dependencies, Visual Studio will use NuGet to retrieve the specified versions of each package the next time you build. If you are not using Visual Studio, use the `dotnet restore` command to update your dependencies. ### Editing the project file directly Your project’s `.csproj` file contains an `` container that lists your dependencies as ` ``` ### The Visual Studio NuGet GUI Visual Studio’s NuGet tools are accessible from **Tools** > **NuGet Package Manager** > **Manage NuGet Packages for Solution**. Use the **Browse** tab to find the AWS Construct Library packages you want to install. You can choose the desired version, including prerelease versions of your modules, and add them to any of the open projects. **Note** All AWS Construct Library modules deemed "experimental" (see [AWS CDK versioning](versioning.md)) are flagged as prerelease in NuGet and have an `alpha` name suffix. ![\[NuGet package manager showing Amazon CDK alpha packages for various services.\]](http://docs.aws.amazon.com/cdk/v2/guide/images/visual-studio-nuget.png) Look on the **Updates** page to install new versions of your packages. ### The NuGet console The NuGet console is a PowerShell-based interface to NuGet that works in the context of a Visual Studio project. You can open it in Visual Studio by choosing **Tools** > **NuGet Package Manager** > **Package Manager Console**. For more information about using this tool, see [Install and Manage Packages with the Package Manager Console in Visual Studio](https://docs.microsoft.com/en-us/nuget/consume-packages/install-use-packages-powershell). ### The `dotnet` command The `dotnet` command is the primary command line tool for working with Visual Studio C\$1 projects. You can invoke it from any Windows command prompt. Among its many capabilities, `dotnet` can add NuGet dependencies to a Visual Studio project. Assuming you’re in the same directory as the Visual Studio project (`.csproj`) file, issue a command like the following to install a package. Because the main CDK library is included when you create a project, you only need to explicitly install experimental modules. Experimental modules require you to specify an explicit version number. ``` dotnet add package Amazon.CDK.AWS.IoT.Alpha -v ``` You can issue the command from another directory. To do so, include the path to the project file, or to the directory that contains it, after the `add` keyword. The following example assumes that you are in your AWS CDK project’s main directory. ``` dotnet add src/ package Amazon.CDK.AWS.IoT.Alpha -v ``` To install a specific version of a package, include the `-v` flag and the desired version. To update a package, issue the same `dotnet add` command you used to install it. For experimental modules, again, you must specify an explicit version number. For more information about managing packages using the `dotnet` command, see [Install and Manage Packages Using the dotnet CLI](https://docs.microsoft.com/en-us/nuget/consume-packages/install-use-packages-dotnet-cli). ### The `nuget` command The `nuget` command line tool can install and update NuGet packages. However, it requires your Visual Studio project to be set up differently from the way `cdk init` sets up projects. (Technical details: `nuget` works with `Packages.config` projects, while `cdk init` creates a newer-style `PackageReference` project.) We do not recommend the use of the `nuget` tool with AWS CDK projects created by `cdk init`. If you are using another type of project, and want to use `nuget`, see the [NuGet CLI Reference](https://docs.microsoft.com/en-us/nuget/reference/nuget-exe-cli-reference). ## AWS CDK idioms in C\$1 ### Props All AWS Construct Library classes are instantiated using three arguments: the *scope* in which the construct is being defined (its parent in the construct tree), an *id*, and *props*, a bundle of key/value pairs that the construct uses to configure the resources it creates. Other classes and methods also use the "bundle of attributes" pattern for arguments. In C\$1, props are expressed using a props type. In idiomatic C\$1 fashion, we can use an object initializer to set the various properties. Here we’re creating an Amazon S3 bucket using the `Bucket` construct; its corresponding props type is `BucketProps`. ``` var bucket = new Bucket(this, "amzn-s3-demo-bucket", new BucketProps { Versioned = true }); ``` **Tip** Add the package `Amazon.JSII.Analyzers` to your project to get required-values checking in your props definitions inside Visual Studio. When extending a class or overriding a method, you may want to accept additional props for your own purposes that are not understood by the parent class. To do this, subclass the appropriate props type and add the new attributes. ``` // extend BucketProps for use with MimeBucket class MimeBucketProps : BucketProps { public string MimeType { get; set; } } // hypothetical bucket that enforces MIME type of objects inside it class MimeBucket : Bucket { public MimeBucket( readonly Construct scope, readonly string id, readonly MimeBucketProps props=null) : base(scope, id, props) { // ... } } // instantiate our MimeBucket class var bucket = new MimeBucket(this, "amzn-s3-demo-bucket", new MimeBucketProps { Versioned = true, MimeType = "image/jpeg" }); ``` When calling the parent class’s initializer or overridden method, you can generally pass the props you received. The new type is compatible with its parent, and extra props you added are ignored. A future release of the AWS CDK could coincidentally add a new property with a name you used for your own property. This won’t cause any technical issues using your construct or method (since your property isn’t passed "up the chain," the parent class or overridden method will simply use a default value) but it may cause confusion for your construct’s users. You can avoid this potential problem by naming your properties so they clearly belong to your construct. If there are many new properties, bundle them into an appropriately-named class and pass them as a single property. ### Generic structures In some APIs, the AWS CDK uses JavaScript arrays or untyped objects as input to a method. (See, for example, AWS CodeBuild’s [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_codebuild.BuildSpec.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_codebuild.BuildSpec.html) method.) In C\$1, these objects are represented as `System.Collections.Generic.Dictionary`. In cases where the values are all strings, you can use `Dictionary`. JavaScript arrays are represented as `object[]` or `string[]` array types in C\$1. **Tip** You might define short aliases to make it easier to work with these specific dictionary types. ``` using StringDict = System.Collections.Generic.Dictionary; using ObjectDict = System.Collections.Generic.Dictionary; ``` ### Missing values In C\$1, missing values in AWS CDK objects such as props are represented by `null`. The null-conditional member access operator `?.` and the null coalescing operator `??` are convenient for working with these values. ``` // mimeType is null if props is null or if props.MimeType is null string mimeType = props?.MimeType; // mimeType defaults to text/plain. either props or props.MimeType can be null string MimeType = props?.MimeType ?? "text/plain"; ``` ## Build and run CDK applications The AWS CDK automatically compiles your app before running it. However, it can be useful to build your app manually to check for errors and run tests. You can do this by pressing F6 in Visual Studio or by issuing `dotnet build src` from the command line, where `src` is the directory in your project directory that contains the Visual Studio Solution (`.sln`) file. # Working with the AWS CDK in Go Go is a fully-supported client language for the AWS Cloud Development Kit (AWS CDK) and is considered stable. Working with the AWS CDK in Go uses familiar tools. The Go version of the AWS CDK even uses Go-style identifiers. Unlike the other languages the CDK supports, Go is not a traditional object-oriented programming language. Go uses composition where other languages often leverage inheritance. We have tried to employ idiomatic Go approaches as much as possible, but there are places where the CDK may differ. This topic provides guidance when working with the AWS CDK in Go. See the [announcement blog post](https://aws.amazon.com/blogs/developer/getting-started-with-the-aws-cloud-development-kit-and-go/) for a walkthrough of a simple Go project for the AWS CDK. ## Get started with Go To work with the AWS CDK, you must have an AWS account and credentials and have installed Node.js and the AWS CDK Toolkit. See [Getting started with the AWS CDK](getting-started.md). The Go bindings for the AWS CDK use the standard [Go toolchain](https://golang.org/dl/), v1.23 or later. You can use the editor of your choice. **Note** Third-party language deprecation: language version is only supported until its EOL (End Of Life) shared by the vendor or community and is subject to change with prior notice. ## Creating a project You create a new AWS CDK project by invoking `cdk init` in an empty directory. Use the `--language` option and specify `go`: ``` mkdir my-project cd my-project cdk init app --language go ``` `cdk init` uses the name of the project folder to name various elements of the project, including classes, subfolders, and files. Hyphens in the folder name are converted to underscores. However, the name should otherwise follow the form of a Go identifier; for example, it should not start with a number or contain spaces. The resulting project includes a reference to the core AWS CDK Go module, `github.com/aws/aws-cdk-go/awscdk/v2`, in `go.mod`. Issue `go get` to install this and other required modules. ## Managing AWS Construct Library modules In most AWS CDK documentation and examples, the word "module" is often used to refer to AWS Construct Library modules, one or more per AWS service, which differs from idiomatic Go usage of the term. The CDK Construct Library is provided in one Go module with the individual Construct Library modules, which support the various AWS services, provided as Go packages within that module. Some services' AWS Construct Library support is in more than one Construct Library module (Go package). For example, Amazon Route 53 has three Construct Library modules in addition to the main `awsroute53` package, named `awsroute53patterns`, `awsroute53resolver`, and `awsroute53targets`. The AWS CDK’s core package, which you’ll need in most AWS CDK apps, is imported in Go code as `github.com/aws/aws-cdk-go/awscdk/v2`. Packages for the various services in the AWS Construct Library live under `github.com/aws/aws-cdk-go/awscdk/v2`. For example, the Amazon S3 module’s namespace is `github.com/aws/aws-cdk-go/awscdk/v2/awss3`. ``` import ( "github.com/aws/aws-cdk-go/awscdk/v2/awss3" // ... ) ``` Once you have imported the Construct Library modules (Go packages) for the services you want to use in your app, you access constructs in that module using, for example, `awss3.Bucket`. ## Managing dependencies in Go In Go, dependencies versions are defined in `go.mod`. The default `go.mod` is similar to the one shown here. ``` module my-package go 1.16 require ( github.com/aws/aws-cdk-go/awscdk/v2 v2.16.0 github.com/aws/constructs-go/constructs/v10 v10.0.5 github.com/aws/jsii-runtime-go v1.29.0 ) ``` Package names (modules, in Go parlance) are specified by URL with the required version number appended. Go's module system does not support version ranges. Issue the `go get` command to install all required modules and update `go.mod`. To see a list of available updates for your dependencies, issue `go list -m -u all`. ## AWS CDK idioms in Go ### Field and method names Field and method names use camel casing (`likeThis`) in TypeScript, the CDK’s language of origin. In Go, these follow Go conventions, so are Pascal-cased (`LikeThis`). ### Cleaning up In your `main` method, use `defer jsii.Close()` to make sure your CDK app cleans up after itself. ### Missing values and pointer conversion In Go, missing values in AWS CDK objects such as property bundles are represented by `nil`. Go doesn’t have nullable types; the only type that can contain `nil` is a pointer. To allow values to be optional, then, all CDK properties, arguments, and return values are pointers, even for primitive types. This applies to required values as well as optional ones, so if a required value later becomes optional, no breaking change in type is needed. When passing literal values or expressions, use the following helper functions to create pointers to the values. + `jsii.String` + `jsii.Number` + `jsii.Bool` + `jsii.Time` For consistency, we recommend that you use pointers similarly when defining your own constructs, even though it may seem more convenient to, for example, receive your construct’s `id` as a string rather than a pointer to a string. When dealing with optional AWS CDK values, including primitive values as well as complex types, you should explicitly test pointers to make sure they are not `nil` before doing anything with them. Go does not have "syntactic sugar" to help handle empty or missing values as some other languages do. However, required values in property bundles and similar structures are guaranteed to exist (construction fails otherwise), so these values need not be `nil`-checked. ### Constructs and Props Constructs, which represent one or more AWS resources and their associated attributes, are represented in Go as interfaces. For example, `awss3.Bucket` is an interface. Every construct has a factory function, such as `awss3.NewBucket`, to return a struct that implements the corresponding interface. All factory functions take three arguments: the `scope` in which the construct is being defined (its parent in the construct tree), an `id`, and `props`, a bundle of key/value pairs that the construct uses to configure the resources it creates. The "bundle of attributes" pattern is also used elsewhere in the AWS CDK. In Go, props are represented by a specific struct type for each construct. For example, an `awss3.Bucket` takes a props argument of type `awss3.BucketProps`. Use a struct literal to write props arguments. ``` var bucket = awss3.NewBucket(stack, jsii.String("amzn-s3-demo-bucket"), &awss3.BucketProps{ Versioned: jsii.Bool(true), }) ``` ### Generic structures In some places, the AWS CDK uses JavaScript arrays or untyped objects as input to a method. (See, for example, AWS CodeBuild’s [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_codebuild.BuildSpec.html#static-fromwbrobjectvalue](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_codebuild.BuildSpec.html#static-fromwbrobjectvalue) method.) In Go, these objects are represented as slices and an empty interface, respectively. The CDK provides variadic helper functions such as `jsii.Strings` for building slices containing primitive types. ``` jsii.Strings("One", "Two", "Three") ``` ### Working with any slice Certain constructs expect properties that are a list of multiple types (union types in TypeScript). In Go, these are as a slice of any (`*[]any`). The `any` ensures that the compiler will allow the assignment of different types there. Refer to the documentation for the ` [AWS CDK Go package](https://pkg.go.dev/github.com/aws/aws-cdk-go/awscdk/v2) ` to find out what the allowed types are. To work with such properties, use the helper functions provided by `jsii` to create slices of any from different types: + `jsii.AnySlice` + `jsii.AnyStrings` + `jsii.AnyNumbers` For example: ``` func Arns() *[]*string { a := "arn:aws:s3:::bucket1" b := "arn:aws:s3:::bucket2" return &[]*string{&a, &b} } awsiam.NewCfnUser(stack, jsii.String("User"), &awsiam.CfnUserProps{ ManagedPolicyArns: jsii.AnySlice(Arns()) // or ManagedPolicyArns: jsii.AnyStrings("arn:aws:s3:::bucket1", "arn:aws:s3:::bucket2") // or ManagedPolicyArns: &[]interface{}{ jsii.String("arn:aws:s3:::bucket1"), jsii.String("arn:aws:s3:::bucket2"), } }) ``` This approach ensures that your slices are correctly interpreted by the CDK, avoiding deserialization errors when deploying or synthesizing your stacks. ### Developing custom constructs In Go, it is usually more straightforward to write a new construct than to extend an existing one. First, define a new struct type, anonymously embedding one or more existing types if extension-like semantics are desired. Write methods for any new functionality you’re adding and the fields necessary to hold the data they need. Define a props interface if your construct needs one. Finally, write a factory function `NewMyConstruct()` to return an instance of your construct. If you are simply changing some default values on an existing construct or adding a simple behavior at instantiation, you don’t need all that plumbing. Instead, write a factory function that calls the factory function of the construct you’re "extending." In other CDK languages, for example, you might create a `TypedBucket` construct that enforces the type of objects in an Amazon S3 bucket by overriding the `s3.Bucket` type and, in your new type’s initializer, adding a bucket policy that allows only specified filename extensions to be added to the bucket. In Go, it is easier to simply write a `NewTypedBucket` that returns an `s3.Bucket` (instantiated using `s3.NewBucket`) to which you have added an appropriate bucket policy. No new construct type is necessary because the functionality is already available in the standard bucket construct; the new "construct" just provides a simpler way to configure it. ## Building, synthesizing, and deploying The AWS CDK automatically compiles your app before running it. However, it can be useful to build your app manually to check for errors and to run tests. You can do this by issuing `go build` at a command prompt while in your project’s root directory. Run any tests you’ve written by running `go test` at a command prompt. ## Troubleshooting If you encounter a compiler error like the following, it means that string slices were passed directly to a property expecting a slice of any. ``` Cannot use 'jsii.Strings("arn:aws:s3:::bucket1", "arn:aws:s3:::bucket2")' (type *[]*string) as the type *[]interface{} ``` To resolve this error, replace `jsii.Strings()` with `jsii.AnyStrings()`. See this ` [CDK GitHub issue](https://github.com/aws/aws-cdk/issues/35630) ` for more context and additional solutions.