Skip to main content

Environment Variables

Environment variables provide a flexible way to configure your CDK applications across different deployment stages without hardcoding values.

Overview​

The nx-cdk plugin supports environment variables at multiple levels:

  • System-level: Standard environment variables from your shell
  • Project-level: Defined in .env files
  • Stage-specific: Override values per deployment stage

Setting Environment Variables​

.env Files​

Create .env files in your project root to define environment variables:

.env            # defaults for all envs
.env.dev        # overrides for dev
.env.staging    # overrides for staging
.env.prod       # overrides for prod

Example .env.dev:

TABLE_THROUGHPUT=1
QUEUE_BATCH_SIZE=5
API_STAGE=dev
ENABLE_DLQ=true

Precedence​

  • CLI/exported variables > .env.<env> > .env
  • Avoid committing secrets; prefer CI secrets, SSM, or Secrets Manager

Loading Environment Variables​

Use dotenv (or equivalent) in your CDK app and/or Lambda code:

// cdk-app bootstrap (e.g., src/main.ts)
import 'dotenv/config';
// or:
// import * as dotenv from 'dotenv';
// dotenv.config({ path: `.env.${process.env.NX_TASK_TARGET_CONFIGURATION ?? 'dev'}` });

Determine which file to load based on the Nx configuration:

const envName = process.env.NX_TASK_TARGET_CONFIGURATION ?? 'dev';

Using Env Vars in CDK​

Configure stacks with env-driven parameters​

import { App, Stack } from 'aws-cdk-lib';

const app = new App();
const envName = process.env.NX_TASK_TARGET_CONFIGURATION ?? 'dev';

const writeCapacity = Number(process.env.TABLE_THROUGHPUT ?? 5);
const enableDlq = String(process.env.ENABLE_DLQ ?? 'true') === 'true';

class MyStack extends Stack {
  // define resources using writeCapacity, enableDlq, etc.
}

new MyStack(app, `orders-${envName}`);

Pass env vars to Lambda functions​

// example: lambda function environment
myFn.addEnvironment('TABLE_NAME', 'OrdersTable');
myFn.addEnvironment('LOG_LEVEL', process.env.LOG_LEVEL ?? 'info');

In your Lambda handler:

export const handler = async () => {
  const table = process.env.TABLE_NAME;
  const level = process.env.LOG_LEVEL ?? 'info';
};

Nx Integration​

Select environment via Nx configuration; your code can use NX_TASK_TARGET_CONFIGURATION to load the right .env.* file.

nx deploy orders --configuration=dev
nx deploy orders --configuration=staging
nx deploy orders --configuration=prod

See also:

CI/CD and Secrets​

  • Inject sensitive values via CI secrets (e.g., GitHub Actions secrets, OIDC + SSM/Secrets Manager)
  • Do not commit secrets to .env files
  • For CI, export variables before running nx/cdk commands

GitHub Actions example:

- name: Export env
  run: |
    echo "LOG_LEVEL=warn" >> $GITHUB_ENV
    echo "ENABLE_DLQ=true" >> $GITHUB_ENV
- name: Deploy
  run: npx nx deploy orders --configuration=prod

Best Practices​

  • No secrets in git: use AWS Secrets Manager/SSM for sensitive data
  • Typed parsing: coerce types (Number, booleans) at the boundary
  • Defaults: provide sane defaults for local dev
  • Traceability: output critical config values as CloudFormation Outputs where useful (non-secret)
  • Consistency: align env names with Nx configurations (dev, staging, prod)