AWS cdk documentation change
Summary
Updated formatting, syntax, and structure of JavaScript CDK documentation. Changes include command formatting with $, markdown corrections, dependency management clarifications, and TypeScript-to-JS adaptation notes.
Security assessment
The changes are primarily formatting improvements, command syntax adjustments, and documentation clarifications. There is no mention of security vulnerabilities, patches, or explicit security feature additions. Notes about dependency updates and testing are general best practices but not tied to specific security issues.
Diff
diff --git a/cdk/v2/guide/work-with-cdk-javascript.md b/cdk/v2/guide/work-with-cdk-javascript.md index a8e650a31..45a092fad 100644 --- a//cdk/v2/guide/work-with-cdk-javascript.md +++ b//cdk/v2/guide/work-with-cdk-javascript.md @@ -15,21 +14,0 @@ You can use any editor or IDE. Many AWS CDK developers use [Visual Studio Code]( -###### Topics - - * Get started with JavaScript - - * Creating a project - - * Using local cdk - - * Managing AWS Construct Library modules - - * Managing dependencies in JavaScript - - * AWS CDK idioms in JavaScript - - * Using TypeScript examples with JavaScript - - * Migrating to TypeScript - - - - @@ -51,3 +30,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 javascript + $ mkdir my-project + $ cd my-project + $ cdk init app --language javascript @@ -55 +34 @@ You create a new AWS CDK project by invoking `cdk init` in an empty directory. U -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. +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. @@ -65 +44 @@ Some teams prefer to specify all dependencies within each project, including too -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. +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. @@ -67 +46 @@ The CDK includes a dependency for the CDK Toolkit in the JavaScript project temp -Operation | Use global CDK Toolkit | Use local CDK Toolkit +Operation | Use global tools | Use local tools @@ -69,2 +48,2 @@ Operation | Use global CDK Toolkit | Use local CDK Toolkit -Initialize project | `cdk init --language javascript` | `npx aws-cdk init --language javascript` -Run CDK Toolkit command | `cdk ...` | `npm run cdk ...` or `npx aws-cdk ...` +**Initialize project** | `cdk init --language javascript` | `npx aws-cdk init --language javascript` +**Run CDK Toolkit command** | `cdk …` | `npm run cdk …` or `npx aws-cdk …` @@ -82 +61 @@ macOS/Linux - alias cdk="npx aws-cdk" + $ alias cdk="npx aws-cdk" @@ -94 +73 @@ 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-lib/`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-lib/<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). @@ -107 +86 @@ 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`: @@ -133 +112 @@ In JavaScript, you import modules into your code under the same name you use to -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`. +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`. @@ -135 +114 @@ In JavaScript 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. @@ -137 +116 @@ 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. @@ -183 +162 @@ 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. @@ -209 +188 @@ 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. @@ -213 +192 @@ 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. @@ -235 +214 @@ 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). @@ -239 +218 @@ 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. @@ -247 +226 @@ All AWS Construct Library classes are instantiated using three arguments: the _s -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. +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. @@ -251 +230 @@ When subclassing an AWS Construct Library class (or overriding a method that tak -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: @@ -267 +246 @@ Missing values in an object (such as `props`) have the value `undefined` in Java -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: +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: @@ -280 +259 @@ Node.js 14.0 and later support new operators that can simplify the handling of u -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. +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. @@ -328 +307 @@ JavaScript -An alternative to using the old-style imports and exports is to use the [`esm`](https://www.npmjs.com/package/esm) module. +An alternative to using the old-style imports and exports is to use the [esm](https://www.npmjs.com/package/esm) module. @@ -330 +309 @@ An alternative to using the old-style imports and exports is to use the [`esm`]( -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: +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: @@ -351 +330 @@ TypeScript - var encrypted**: boolean** = true; + var encrypted: boolean = true; @@ -354 +333 @@ TypeScript - bucket**: s3.Bucket** ; + bucket: s3.Bucket; @@ -358 +337 @@ TypeScript - function makeEnv(account**: string** , region**: string**) **: object** { + function makeEnv(account: string, region: string) : object { @@ -369 +348 @@ JavaScript - bucket**= undefined** ; + bucket = undefined; @@ -385 +364 @@ In TypeScript, interfaces are used to give bundles of required and optional prop -JavaScript does not have an interface feature, so once you've removed the type annotations, delete the interface declarations entirely. +JavaScript does not have an interface feature, so once you’ve removed the type annotations, delete the interface declarations entirely. @@ -387 +366 @@ JavaScript does not have an interface feature, so once you've removed the type a -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, `<LikeThis>`; these casts, too, must be removed. +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, `<LikeThis>`; these casts, too, must be removed. @@ -391 +370 @@ Finally, TypeScript supports the access modifiers `public`, `protected`, and `pr -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. +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. @@ -395 +374 @@ Knowing how to identify and remove these TypeScript features goes a long way tow -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. +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. @@ -397 +376 @@ Many JavaScript developers move to [TypeScript](https://www.typescriptlang.org/) -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. +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.