AWS cdk documentation change
Summary
Updated documentation formatting, code examples, and markdown syntax. Removed redundant 'Topics' section and improved command-line examples with $ prompts. Fixed typographical quotes and code formatting.
Security assessment
Changes are primarily grammatical improvements, markdown formatting adjustments, and code example clarifications. No references to security vulnerabilities, mitigations, or security feature additions are present in the diff.
Diff
diff --git a/cdk/v2/guide/work-with-cdk-typescript.md b/cdk/v2/guide/work-with-cdk-typescript.md index 5f3a79b26..e16e11dd0 100644 --- a//cdk/v2/guide/work-with-cdk-typescript.md +++ b//cdk/v2/guide/work-with-cdk-typescript.md @@ -11 +11 @@ This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on -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/). +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/). @@ -15,19 +14,0 @@ You can use any editor or IDE. Many AWS CDK developers use [Visual Studio Code]( -###### Topics - - * Get started with TypeScript - - * Creating a project - - * Using local tsc and cdk - - * Managing AWS Construct Library modules - - * Managing dependencies in TypeScript - - * AWS CDK idioms in TypeScript - - * Build and run CDK apps - - - - @@ -38 +19 @@ To work with the AWS CDK, you must have an AWS account and credentials and have -You also need TypeScript itself (version 3.8 or later). If you don't already have it, you can install it using `npm`. +You also need TypeScript itself (version 3.8 or later). If you don’t already have it, you can install it using `npm`. @@ -41 +22 @@ You also need TypeScript itself (version 3.8 or later). If you don't already hav - npm install -g typescript + $ npm install -g typescript @@ -58,3 +39,3 @@ You create a new AWS CDK project by invoking `cdk init` in an empty directory. U - mkdir my-project - cd my-project - cdk init app --language typescript + $ mkdir my-project + $ cd my-project + $ cdk init app --language typescript @@ -72 +53 @@ Some teams prefer to specify all dependencies within each project, including too -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. +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. @@ -76,3 +57,3 @@ 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 ...` +**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 …` @@ -90 +71 @@ macOS/Linux - alias cdk="npx aws-cdk" + $ alias cdk="npx aws-cdk" @@ -102 +83 @@ Use the Node Package Manager (`npm`) to install and update AWS Construct Library -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/`SERVICE-NAME`-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). +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/<SERVICE-NAME>-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). @@ -111 +92 @@ For example, the command below installs the experimental module for AWS CodeStar - npm install @aws-cdk/aws-codestar-alpha + $ npm install @aws-cdk/aws-codestar-alpha @@ -115 +96 @@ Some services' Construct Library support is in more than one namespace. For exam -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`: +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`: @@ -118 +99 @@ Your project's dependencies are maintained in `package.json`. You can edit this - npm update + $ npm update @@ -141 +122 @@ In TypeScript, you import modules into your code under the same name you use to -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`. +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`. @@ -143 +124 @@ In TypeScript CDK projects, dependencies are specified in the `package.json` fil -When you install a package using **npm install** , NPM records the package in `package.json` for you. +When you install a package using `npm install`, NPM records the package in `package.json` for you. @@ -145 +126 @@ When you install a package using **npm install** , NPM records the package in `p -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. +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. @@ -191 +172 @@ Specify versions of libraries and tools needed to test your app (for example, th -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. +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. @@ -217 +198 @@ In `devDependencies`, specify the tools and libraries you need for testing, opti -`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. +`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. @@ -221 +202 @@ In `devDependencies`, specify the tools and libraries you need for testing, opti -Run the following command to install your project's dependencies. +Run the following command to install your project’s dependencies. @@ -238 +219 @@ Yarn - yarn upgrade + $ yarn upgrade @@ -241 +222 @@ Yarn - yarn install --frozen-lockfile + $ yarn install --frozen-lockfile @@ -243 +224 @@ Yarn -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). +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). @@ -247 +228 @@ To update the installed modules, the preceding **npm install** and **yarn upgrad -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. +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. @@ -255 +236 @@ All AWS Construct Library classes are instantiated using three arguments: the _s -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 [Bucket](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 [BucketProps](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html) interface. +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 [`Bucket`](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 [`BucketProps`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html) interface. @@ -257 +238 @@ In TypeScript, the shape of `props` is defined using an interface that tells you -If a property is itself an object, for example the [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 [RedirectTarget](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.RedirectTarget.html). +If a property is itself an object, for example the [`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 [`RedirectTarget`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.RedirectTarget.html). @@ -261 +242 @@ If you are subclassing an AWS Construct Library class (or overriding a method th -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: +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: @@ -274 +255 @@ Missing values in an object (such as props) have the value `undefined` in TypeSc -Generally, you should be in the project's root directory when building and running your application. +Generally, you should be in the project’s root directory when building and running your application.