Merge branch 'mainline' into feat/s3-integration

# Conflicts: # packages/type-safe-api/src/construct/spec/utils.ts
aws · Nov 4, 2023 · 0a66043 · 0a66043
2 parents f220e85 + 9870c9b
commit 0a66043
Show file tree

Hide file tree

Showing 270 changed files with 21,839 additions and 5,581 deletions.
diff --git a/.eslintrc.json b/.eslintrc.json
diff --git a/.gitattributes b/.gitattributes
diff --git a/.gitignore b/.gitignore
diff --git a/.npmignore b/.npmignore
diff --git a/.npmrc b/.npmrc
diff --git a/.nxignore b/.nxignore
diff --git a/.prettierignore b/.prettierignore
diff --git a/.projen/deps.json b/.projen/deps.json
diff --git a/.projen/files.json b/.projen/files.json
diff --git a/.projen/tasks.json b/.projen/tasks.json
diff --git a/.syncpackrc.json b/.syncpackrc.json
diff --git a/docs/.eslintrc.json b/docs/.eslintrc.json
diff --git a/docs/.gitattributes b/docs/.gitattributes
diff --git a/docs/.gitignore b/docs/.gitignore
diff --git a/docs/.npmignore b/docs/.npmignore
diff --git a/docs/.projen/deps.json b/docs/.projen/deps.json
diff --git a/docs/.projen/files.json b/docs/.projen/files.json
diff --git a/docs/.projen/tasks.json b/docs/.projen/tasks.json
diff --git a/docs/content/getting_started/index.md b/docs/content/getting_started/index.md
@@ -182,21 +182,30 @@ git config --global user.email "[email protected]"
 git config --global user.name "username"
 ```
 
+### JDK + Maven (If using Type Safe API)
+
+The Type Safe API requires JDK >= 11 and Maven >= 3.8 in order to perform the required code generation.
+
+To install these, follow the below links:
+
+- JDK: We recommend installing any Coretto version >= 11 https://docs.aws.amazon.com/corretto/
+- Maven: You can any version of Maven >= 3.8: https://maven.apache.org/install.html
+
 ### Language specific
 
 Other prerequisites depend on the language in which you develop AWS PDK projects and are as follows.
 
 === "TYPESCRIPT"
-    - `Node >= 16`
-    - `PNPM >= 8.6.3` [if using `--package-manager=pnpm` flag to bootstrap]
+    - `PNPM >= 8.6.3` [if using `--package-manager=pnpm` flag to bootstrap]: https://pnpm.io/installation
+    - `YARN` [if `--package-manager` flag is unset]: https://classic.yarnpkg.com/lang/en/docs/install/#mac-stable
 
 === "PYTHON"
-    - `Python >= 3.9`
-    - `Poetry >= 1.5.1`
+    - `Python >= 3.9`: https://github.com/pyenv/pyenv
+    - `Poetry >= 1.5.1`: https://python-poetry.org/docs/
+    - `YARN`: https://classic.yarnpkg.com/lang/en/docs/install/#mac-stable
 
 === "JAVA"
-    - `JDK >= 11`
-    - `Apache Maven >= 3.8`
+    - `YARN`: https://classic.yarnpkg.com/lang/en/docs/install/#mac-stable
 
 ### Install the AWS CDK
 

diff --git a/docs/content/getting_started/shopping_list_app.md b/docs/content/getting_started/shopping_list_app.md
@@ -708,7 +708,7 @@ We are now ready to deploy our API. To do so, run the following steps:
 ```bash
 pdk build
 cd packages/infra
-pdk run deploy --require-approval never
+pdk deploy:dev
 ```
 
 Once the deployment completes, we can test our API by navigating the the website (either via Cloudfront or locally) and trying out the API Explorer.
@@ -1192,7 +1192,7 @@ If you are happy with your website locally, you can go ahead and deploy it to AW
 ```bash
 pdk build
 cd packages/infra
-pdk run deploy --require-approval never
+pdk deploy:dev
 ```
 
 Once the deployment completes, navigate to your cloudfront URL to play around with your deployed website.

diff --git a/docs/content/getting_started/your_first_aws_pdk_project.md b/docs/content/getting_started/your_first_aws_pdk_project.md
@@ -26,72 +26,7 @@ We'll also show how to add a new API operation, implement an API handler, and wi
 
 ## Prerequisites
 
-The following subsections outline what you need to install and use the AWS PDK.
-
-### Node runtime
-
-All AWS PDK developers, even those working in Python or Java, need Node.js 16 or later. All supported languages use the same backend, which runs on Node.js. We recommend a version in active long-term support. Your organization may have a different recommendation.
-
-!!!tip
-    We recommend installing [`nvm`](https://github.com/nvm-sh/nvm#installing-and-updating) and configuring it to use Node 18.
-
-### PDK CLI
-
-Once your NodeJs ruuntime is set up, run the following command to install the pdk CLI:
-
-```bash
-npm install -g @aws/pdk
-```
-
-Run the following command to verify correct installation and print the version number of the AWS PDK.
-
-`pdk --version`
-
-!!!warning
-    The `pdk` command is a wrapper command which delegates to either a package manager or a projen command depending on the context. As such it may be possible that certain arguments may not operate as expected.
-
-### Git
-
-[Git](https://git-scm.com/) is also required to be installed and configured when bootstrapping new applications unless the `--no-git` flag is specified when executing the `pdk new` command.
-
-Ensure to configure a username and email via the below commands once installed:
-
-```bash
-git config --global user.email "[email protected]"
-git config --global user.name "username"
-```
-
-### Language specific
-
-Other prerequisites depend on the language in which you develop AWS PDK projects and are as follows.
-
-=== "TYPESCRIPT"
-    - `Node >= 16`
-    - `PNPM >= 8.6.3` [if using `--package-manager=pnpm` flag to bootstrap]
-
-=== "PYTHON"
-    - `Python >= 3.9`
-    - `Poetry >= 1.5.1`
-
-=== "JAVA"
-    - `JDK >= 11`
-    - `Apache Maven >= 3.8`
-
-### Install the AWS CDK
-
-You will need to install the AWS CDK in order to bootstrap and deploy your infrastructure to AWS. To install, run the following command:
-
-`npm install -g aws-cdk`
-
-Run the following command to verify correct installation and print the version number of the AWS CDK.
-
-`cdk --version`
-
-### Authentication with AWS
-
-You must establish how the AWS CDK authenticates with AWS when deploying infrastructure. There are different ways in which you can configure programmatic access to AWS resources, depending on the environment and the AWS access available to you.
-
-For an in depth guide, please refer to: https://docs.aws.amazon.com/sdkref/latest/guide/access.html
+Refer to [prerequisites](./index.md#prerequisites).
 
 ## Create your project
 
@@ -151,7 +86,7 @@ Inspecting the `projenrc` file, we notice that a single construct is instantiate
     - Any parameter listed here can be passed in via the `pdk new` command i.e: `--name="some-other-name"`.
 - For python, the moduleName defaults to a snake-cased project name.
 
-You will also notice that the `synth()` method is called on this instance at the end of the file. When you run the `pdk` command, this file will be executed by your runtime and will synthesize this instance which will result in all the files that you see in the previous image. 
+You will also notice that the `synth()` method is called on this instance at the end of the file. When you run the `pdk` command, this file will be executed by your runtime and will synthesize this instance which will result in all the files that you see in the previous image.
 
 !!!info
     Whenever you change the `projenrc` file, make sure you run the `pdk` command from the root of your project to ensure your files are synthesized.
@@ -358,7 +293,7 @@ For more details on these packages, refer to the [Type-Safe API Developer Guide]
 Now, lets build our API by running `pdk build` from the root of our monorepo. You will notice that each package in the monorepo is built in dependency order.
 
 !!!tip
-    If you run the `pdk build` command again without changing any files, you will notice that the build completes in a fraction of the time (1.7s as per below snippet) as it uses [cached results](https://nx.dev/concepts/how-caching-works) and will only re-build packages that have changed since the last time it was built.  
+    If you run the `pdk build` command again without changing any files, you will notice that the build completes in a fraction of the time (1.7s as per below snippet) as it uses [cached results](https://nx.dev/concepts/how-caching-works) and will only re-build packages that have changed since the last time it was built.
 
     ```bash
     >  NX   Successfully ran target build for 7 projects
@@ -803,9 +738,12 @@ We now can deploy our infrastructure by running the following command:
 
 ```bash
 cd packages/infra
-pdk run deploy --require-approval never
+pdk deploy:dev
 ```
 
+!!!note
+    The `pdk deploy:dev` command attempts a [CDK hotswap deployment](https://aws.amazon.com/blogs/developer/increasing-development-speed-with-cdk-watch/) if possible. In a production setting (for example in a ci/cd pipeline) use the `pdk deploy` command to ensure a full CloudFormation deployment is performed.
+
 Once the deployment completes, you should see an output that resembles the following:
 
 <img src="../assets/images/deployment_results.png" width="600" />
@@ -821,7 +759,7 @@ In order to log in to your website, you first need to create a Cognito user. By
 1. Navigate to the Cognito AWS console within the account you just deployed to.
 1. Click on the user pool you just created
 1. Click "Create user"
-1. In invitation settings, select "Send an email invitation" 
+1. In invitation settings, select "Send an email invitation"
 1. Enter a username
 1. Enter an email address
 1. In temporary password, select "Generate a password"

diff --git a/docs/package.json b/docs/package.json
diff --git a/docs/project.json b/docs/project.json
diff --git a/docs/tsconfig.dev.json b/docs/tsconfig.dev.json