docs: update migration guide

aws · Sep 4, 2023 · 5fe9871 · 5fe9871
1 parent e391cb0
commit 5fe9871
Show file tree

Hide file tree

Showing 4 changed files with 181 additions and 36 deletions.
diff --git a/docs/content/getting_started/index.md b/docs/content/getting_started/index.md
@@ -147,17 +147,48 @@ The distributables for each language can be used directly as follows:
 
 ## Prerequisites
 
-Here's what you need to install and use the AWS PDK.
+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 "username@domain.com"
+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"
-    - `Typescript >= 5`
+    - `Node >= 16`
+    - `PNPM >= 8.6.3` [if using `--package-manager=pnpm` flag to bootstrap]
 
 === "PYTHON"
     - `Python >= 3.9`
@@ -167,23 +198,9 @@ Other prerequisites depend on the language in which you develop AWS PDK projects
     - `JDK >= 11`
     - `Apache Maven >= 3.8`
 
-## Installation
-### Install the AWS PDK
-
-Install the AWS PDK Toolkit globally using the following Node Package Manager command:
-
-`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.
-
 ### Install the AWS CDK
 
-You will need to install the AWS CDK in order to deploy your infrastructure to AWS. To install, run the following command:
+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`
 

diff --git a/docs/content/getting_started/migration_guide.md b/docs/content/getting_started/migration_guide.md
@@ -376,7 +376,51 @@ In order to make this construct truly cross-platform, we had to make a slight tw
 
 ## Removal of `PDKPipelineTsProject` construct
 
-The `PDKPipelineTsProject` has been removed as it did not provide an adequate level of control of the generated pipeline. If you have instrumented this construct in your `projenrc.ts` file, you can simply change it to use `AwsCdkTypeScriptApp` instead and ensure the `sample` property is set to false to prevent additional sample code being generated. Be sure to ensure the construct has a dependency on `@aws/pdk` as you will still be able to use the `PDKPipeline` CDK construct contained within `@aws/pdk/pipeline`.
+The `PDKPipelineTsProject` has been removed as it did not provide an adequate level of control of the generated pipeline. If you have instrumented this construct in your `projenrc.ts` file, you can simply change it to use `AwsCdkTypeScriptApp` instead and ensure the following:
+
+- `sampleCode` property is set to false to prevent additional sample code being generated.
+- `appEntrypoint` is set to `pipeline.ts` so that the synth command has the correct entrypoint.
+- be sure to ensure the construct has a dependency on `@aws/pdk` as you will still be able to use the `PDKPipeline` CDK construct contained within `@aws/pdk/pipeline`.
+
+=== "BEFORE"
+
+    ```typescript
+    import { PDKPipelineTsProject } from "@aws-prototyping-sdk/pipeline";
+
+    const pipelineProject = new PDKPipelineTsProject({
+        parent: monorepo,
+        outdir: "packages/infra",
+        defaultReleaseBranch: "mainline",
+        name: "infra",
+        cdkVersion: "2.1.0",
+        deps: [
+            "@aws-prototyping-sdk/pipeline",
+            "@aws-prototyping-sdk/static-website",
+            "@aws-prototyping-sdk/identity",
+            "@aws-cdk/aws-cognito-identitypool-alpha@^2.66.1-alpha",
+        ],
+    });
+    ```
+
+=== "AFTER"
+
+    ```typescript hl_lines="1 3 7 10 12"
+    import { AwsCdkTypeScriptApp } from "projen/lib/awscdk"
+
+    const pipelineProject = new AwsCdkTypeScriptApp({
+        parent: monorepo,
+        outdir: "packages/infra",
+        defaultReleaseBranch: "mainline",
+        sampleCode: false,
+        name: "infra",
+        cdkVersion: "2.1.0",
+        appEntrypoint: "pipeline.ts",
+        deps: [
+            "@aws/pdk",
+            "@aws-cdk/aws-cognito-identitypool-alpha@^2.66.1-alpha",
+        ],
+    });
+    ```
 
 ## TypeSafeApi Breaking Changes
 
@@ -630,3 +674,28 @@ In AWS PDK, these classes have been moved out from `Handlers` as their own stand
         }
     }
     ```
+
+## Troubleshooting
+### Missing Polyfill
+
+If you see this error:
+
+```
+Module not found: Error: Can't resolve 'http' in '/Users/xxx/my-project/node_modules/.pnpm/@aws-lambda-powertools+tracer@1.12.1/node_modules/@aws-lambda-powertools/tracer/lib/provider'
+BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default.
+This is no longer the case. Verify if you need this module and configure a polyfill for it.
+```
+
+This is most likley cause by your website having a direct dependency on the Typescript runtime package, since the runtime package has all the server side handlers which is not suitable in a web based context. Ideally your website should only depend on the hooks lib, even if you just use the generated client and not the hooks.
+
+In more abstract terms, it is caused by code within your closure that is using NodeJs native functions, however there is no polyfill available. The easiest way to fix this is to tell webpack to exclude any Node related functions from bundling and assume they are present externally.
+
+To fix this, try adding the following snippet to the project definition within the `projenrc` file:
+
+```
+    rewire: {
+        externalsPresets: {
+            node: true,
+        },
+    }
+```
diff --git a/docs/content/getting_started/your_first_aws_pdk_project.md b/docs/content/getting_started/your_first_aws_pdk_project.md
@@ -24,6 +24,75 @@ This tutorial walks you through creating the PDK Project from start to finish. T
 
 We'll also show how to add a new API operation, implement an API handler, and wire it up in your infrastructure.
 
+## 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 "username@domain.com"
+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
+
 ## Create your project
 
 Each AWS PDK based project should be in its own directory. Create a new directory for your project. Starting in your home directory, or another directory if you prefer, issue the following commands:

diff --git a/scripts/monthly-metrics.sh b/scripts/monthly-metrics.sh
@@ -1,27 +1,17 @@
 #!/bin/bash
 YELLOW='\033[0;33m'
 CYAN='\033[0;36m'
-GREEN='\033[0;32m'
 NO_COLOUR='\033[0m'
 
-TOTAL_NPM_COUNT=0;
-TOTAL_PYPI_COUNT=0;
-printf "`echo $YELLOW`Monthly downloads by Package\n-----------------------------------------------------------\n\n";
+printf "`echo $YELLOW`Monthly downloads for AWS PDK\n-----------------------------------------------------------\n\n";
 
-for NPM_PKG in `npx lerna list`;
-do
-  PKG_DIR=`npx lerna list --scope $NPM_PKG -l | awk '{ print $3 }'`;
-  PYTHON_PKG=`cat $PKG_DIR/package.json | jq -r .jsii.targets.python.distName`;
+NPM_PKG='@aws/pdk'
+PKG_DIR=`npx lerna list --scope $NPM_PKG -l | awk '{ print $3 }'`;
+PYTHON_PKG=`cat $PKG_DIR/package.json | jq -r .jsii.targets.python.distName`;
 
-  NPM_COUNT=`curl -s https://api.npmjs.org/downloads/range/last-month/$NPM_PKG | jq '[.downloads[].downloads | tonumber] | add'`;
-  PYPI_COUNT=`curl -s https://pypistats.org/api/packages/$PYTHON_PKG/recent | jq '.data.last_month'`;
+NPM_COUNT=`curl -s https://api.npmjs.org/downloads/range/last-month/$NPM_PKG | jq '[.downloads[].downloads | tonumber] | add'`;
+PYPI_COUNT=`curl -s https://pypistats.org/api/packages/$PYTHON_PKG/recent | jq '.data.last_month'`;
 
-  [[ "$PYTHON_PKG" == "null" ]] && PYPI_COUNT=0;
+[[ "$PYTHON_PKG" == "null" ]] && PYPI_COUNT=0;
 
-  TOTAL_NPM_COUNT=$(($TOTAL_NPM_COUNT + $NPM_COUNT));
-  TOTAL_PYPI_COUNT=$(($TOTAL_PYPI_COUNT + $PYPI_COUNT));
-
-  printf "$CYAN$NPM_PKG: $NO_COLOUR$NPM_COUNT (NPM), $PYPI_COUNT (PYPI)\n";
-done
-
-printf "$GREEN\nTOTAL: $NO_COLOUR$TOTAL_NPM_COUNT (NPM), $TOTAL_PYPI_COUNT (PYPI) \n";
+printf "$CYAN AWS PDK: $NO_COLOUR$NPM_COUNT (NPM), $PYPI_COUNT (PYPI)\n";