fix(cdk)!: rename DotStack.env to envName for aws-cdk-lib >=2.234.0 compat

packages/cdk/README.md

@@ -22,6 +22,21 @@ Using npm:
 pnpm add @dot/cdk --save-dev
 ```
 
+## Migrating from v4 to v5
+
+`v5` is required for use with `aws-cdk-lib >= 2.234.0`.
+
+In `aws-cdk-lib@2.234.0`, the parent `Stack.env` was changed from a writable property to a getter that returns the resolved AWS `Environment` object (`{ account, region }`). `DotStack` previously assigned a string (`'prod'`, `'dev'`, etc.) to `this.env`, which now throws `TypeError: Cannot set property env of [object Object] which has only a getter`.
+
+To resolve the collision, the field has been renamed:
+
+| v4 (`aws-cdk-lib < 2.234.0`) | v5 (`aws-cdk-lib >= 2.234.0`)                                                       |
+| ---------------------------- | ----------------------------------------------------------------------------------- |
+| `stack.env` → `'prod'`       | `stack.envName` → `'prod'`                                                          |
+|                              | `stack.env` → `Stack.env` getter from `aws-cdk-lib` (returns `{ account, region }`) |
+
+Update any consumer code that read `stack.env` as a deploy-environment string to read `stack.envName` instead. This applies to destructured access (`const { env } = stack`) and template-literal interpolation (`` `${stack.env}` ``) as well — both will now silently read the inherited `aws-cdk-lib` getter (returning `{ account, region }`) rather than the deploy-env string. The `node.tryGetContext('env')` context key is unchanged.
+
 ## Usage
 
 The example below demonstrates a few key features:

packages/cdk/package.json

@@ -15,7 +15,7 @@
     "deploy": "bin/deploy"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "scripts": {
     "build": "pnpm -w package:build $PWD",
@@ -51,11 +51,11 @@
     "@smithy/types": "^4.1.0",
     "@swc-node/register": "^1.10.10",
     "@swc/core": "^1.11.10",
-    "aws-cdk-lib": "^2.185.0",
+    "aws-cdk-lib": "^2.234.0",
     "camelcase": "^6.3.0",
     "cdk-monitoring-constructs": "^9.4.0",
     "chalk": "^4.1.2",
-    "constructs": "^10.4.2",
+    "constructs": "^10.5.0",
     "nanoid": "3.3.4",
     "source-map-support": "^0.5.21",
     "yargs-parser": "^21.1.1"

packages/cdk/src/constructs/Stack.ts

@@ -25,27 +25,27 @@ export class DotStack extends Stack {
   static readonly awsRegion = region;
   public readonly app: App;
   public readonly appName: string;
-  public readonly env: DeployEnvironment;
+  public readonly envName: DeployEnvironment;
   public readonly envPrefix: string;
   public readonly isProd: boolean;
   public readonly ssmPrefix: string;
 
   constructor(scope: App, props: DotStackProps) {
     const stackName = props.name.replace(/-stack$/, '');
-    const env = DEPLOY_ENV as DeployEnvironment;
-    const envPrefix = `${env}-`;
+    const envName = DEPLOY_ENV as DeployEnvironment;
+    const envPrefix = `${envName}-`;
     const stackEnv = { ...(props.env || presetEnv) };
 
     super(scope, `${envPrefix}${stackName}-stack`, { ...props, env: stackEnv });
 
     this.app = scope;
     this.appName = envPrefix + (props.appName || props.name);
-    this.env = env;
+    this.envName = envName;
     this.envPrefix = envPrefix;
-    this.isProd = env === 'prod';
+    this.isProd = envName === 'prod';
     this.node.setContext('appName', this.appName);
-    this.node.setContext('env', this.env);
-    this.ssmPrefix = `/${env}/${props.appName || props.name}`;
+    this.node.setContext('env', this.envName);
+    this.ssmPrefix = `/${envName}/${props.appName || props.name}`;
   }
 
   static baseName(input: string, suffix: string) {

packages/cdk/src/methods/amplify.ts

@@ -20,15 +20,15 @@ interface AddAmplifyAppResult {
 
 export const addAmplifyApp = (options: AddAmplifyAppOptions): AddAmplifyAppResult => {
   const { distPath, domainName, environmentVariables = {}, name, pwaRedirect, scope } = options;
-  const subdomain = options.subdomain ?? scope.env;
+  const subdomain = options.subdomain ?? scope.envName;
   const baseName = DotStack.baseName(name, '-app');
   const appName = scope.resourceName(baseName);
 
   const asset = new Asset(scope, `${appName}-asset`, { path: distPath });
   const app = new Amplify.App(scope, appName, {
     appName
   });
-  const branch = app.addBranch(scope.env, { asset, environmentVariables });
+  const branch = app.addBranch(scope.envName, { asset, environmentVariables });
 
   app.applyRemovalPolicy(RemovalPolicy.DESTROY);
 

packages/cdk/src/methods/dynamo.ts

@@ -74,7 +74,7 @@ export const addTable = (options: AddTableOptions) => {
   const table = new Table(scope, tableId, {
     billingMode: BillingMode.PAY_PER_REQUEST,
     partitionKey,
-    pointInTimeRecovery: scope.env === 'prod',
+    pointInTimeRecovery: scope.envName === 'prod',
     removalPolicy,
     sortKey,
     tableName,

packages/cdk/src/methods/fargate.ts

@@ -90,7 +90,7 @@ export const addFargateService = (options: AddServiceOptions): AddServiceResult
     sslPolicy
   } = options;
   let { vpc } = options;
-  const { env } = scope;
+  const { envName } = scope;
   const baseName = DotStack.baseName(name, 'service');
   const serviceName = scope.resourceName(baseName);
   const certificate = Certificate.fromCertificateArn(scope, `${serviceName}-cert`, certificateArn);
@@ -125,9 +125,9 @@ export const addFargateService = (options: AddServiceOptions): AddServiceResult
       containerPort: port,
       environment: {
         AWS_NODEJS_CONNECTION_REUSE_ENABLED: '1',
-        DEPLOY_ENV: env,
+        DEPLOY_ENV: envName,
         IS_FARGATE: 'true',
-        NODE_ENV: env,
+        NODE_ENV: envName,
         NODE_OPTIONS: `--enable-source-maps --max-old-space-size=${nodeMemorySize}`,
         ...environmentVariables
       },

packages/cdk/src/methods/function.ts

@@ -50,7 +50,7 @@ interface GrantSelfInvokeOptions {
 const FN_TIMEOUT = Duration.minutes(5);
 
 export const addFunctionAlarms = (email: string, fn: Function, fnName: string, scope: DotStack) => {
-  if (scope.env !== 'prod') return;
+  if (scope.envName !== 'prod') return;
 
   const { topic } = addTopic({
     emailAddress: email,

packages/cdk/src/methods/node-function.ts

@@ -49,7 +49,7 @@ export const addNodeFunction = (options: AddNodeFunctionOptions) => {
     storageMb,
     timeout = Duration.minutes(5)
   } = options;
-  const { env } = scope;
+  const { envName } = scope;
 
   const baseName = DotStack.baseName(name, 'fn');
   const baseHooks: ICommandHooks = {
@@ -66,9 +66,9 @@ export const addNodeFunction = (options: AddNodeFunctionOptions) => {
   const defaultEnv: typeof environmentVariables = {
     // Note: https://acloudguru.com/blog/engineering/building-more-cost-effective-lambda-functions-with-1-ms-billing
     AWS_NODEJS_CONNECTION_REUSE_ENABLED: '1',
-    DEPLOY_ENV: env,
+    DEPLOY_ENV: envName,
     IS_LAMBDA: 'true',
-    NODE_ENV: env,
+    NODE_ENV: envName,
     NODE_OPTIONS: `--enable-source-maps --max-old-space-size=${memorySize}`
   };
 
@@ -151,7 +151,7 @@ const setupFunction = ({ fnName, handler, options }: SetupFunctionArgs) => {
     });
 
   if (alarmEmail)
-    addFunctionAlarms(alarmEmail, handler, fnName.replace(`${scope.env}-`, ''), scope);
+    addFunctionAlarms(alarmEmail, handler, fnName.replace(`${scope.envName}-`, ''), scope);
 
   return handler;
 };

packages/cdk/src/methods/signing.ts

@@ -63,7 +63,7 @@ export const addSigningKey = async (scope: DotStack) => {
   }
 
   const { secret: publicKeySecret } = addSecret({
-    name: `${scope.env}-signing-key-pair`,
+    name: `${scope.envName}-signing-key-pair`,
     scope,
     secretName,
     value: keys.keyPair

packages/cdk/src/methods/ws.ts

@@ -151,7 +151,7 @@ export const addWebsocketApi = (options: AddWebsocketApiOptions) => {
   // Note: The following log-related setup is necessary as of 2/22/22
   // eslint-disable-next-line no-new
   const execLogs = new LogGroup(scope, 'ExecutionLogs', {
-    logGroupName: `/aws/apigateway/${api.apiId}/${scope.env}`,
+    logGroupName: `/aws/apigateway/${api.apiId}/${scope.envName}`,
     removalPolicy: RemovalPolicy.DESTROY,
     retention: RetentionDays.ONE_WEEK
   });