Skip to main content

CDK Context Files

CDK context files provide environment-specific settings that configure how your infrastructure is deployed across different stages.

Context File Structure​

Each environment has its own context file:

cdk.json​

Define app entry and reusable context. You can namespace by project and environment.

{
  "app": "npx ts-node --prefer-ts-exts src/main.ts",
  "context": {
    "orders:dev": { "account": "111111111111", "region": "us-east-1" },
    "orders:staging": { "account": "222222222222", "region": "us-east-1" },
    "orders:prod": { "account": "333333333333", "region": "us-east-2" }
  }
}

Per-project cdk.json (optional)​

If your repo has multiple CDK apps, you can keep a cdk.json near each app with its own context namespace.

Supplying Context at Deploy Time​

You can pass additional or overriding context via the CLI:

cdk deploy -c env=dev
cdk deploy -c account=111111111111 -c region=us-east-1

When using Nx executors, context is typically derived from the Nx configuration you select:

nx deploy orders --configuration=dev

Map your Nx dev/staging/prod to a specific context key (e.g., orders:dev) inside your app code.

Reading Context in Your CDK App​

Use App.node.tryGetContext to fetch values and configure stacks accordingly.

// src/main.ts
import { App, Stack, StackProps, Environment } from 'aws-cdk-lib';

const app = new App();

// Example: select a context object by key "orders:<env>"
const envName = process.env.NX_TASK_TARGET_CONFIGURATION ?? process.env.ENV ?? 'dev';
const ctxKey = `orders:${envName}`;
const ctx = app.node.tryGetContext(ctxKey) || {};

const env: Environment = {
  account: ctx.account,
  region: ctx.region,
};

class OrdersStack extends Stack {
  constructor(scope: App, id: string, props?: StackProps) {
    super(scope, id, props);
    // define resources here using additional context values if needed
  }
}

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

Notes:

  • You can also read additional settings (e.g., table throughput, DLQ retention) via app.node.tryGetContext('key') or environment variables.

Nx Integration​

Define per-environment values in your Nx project target configurations and/or .env.* files, then translate them to CDK context keys in your app.

Examples​

Select environment via Nx configuration​

nx deploy orders --configuration=staging

App resolves NX_TASK_TARGET_CONFIGURATION=staging, builds orders:staging context key, and deploys with that account/region.

Override context ad-hoc​

npx cdk deploy -c orders:dev.account=999999999999 -c orders:dev.region=eu-west-1

CDK allows dotted keys for nested overrides.

Best Practices​

  • Namespace keys: use <project>:<env> to avoid collisions across multiple apps.
  • Single source of truth: prefer storing account/region in one place (Nx config or cdk.json) and reference it consistently.
  • No secrets: do not store secrets in context; use AWS Secrets Manager or SSM Parameter Store.
  • Bootstrap: ensure each account/region pair is bootstrapped before first deploy.
  • Consistency: align context names with your Nx configurations (dev, staging, prod).