Stacks

Learn how to create AWS CDK stacks before exploring the starter kit's stack patterns below.

FoundationStack

Source: src/stacks/foundation-stack.ts

Sets up GitHub OpenID Connect (OIDC) and an IAM role for GitHub Actions deploys, plus adds a CloudFormation Toolkit cleaner to keep CDK assets tidy.

Initializers

new FoundationStack(scope: Construct, id: string, props: FoundationStackProps)

Parameters

Name	Type	Description
scope	`Construct`	The scope in which to define this stack.
id	`string`	The scoped stack ID.
props	`FoundationStackProps`	Stack configuration properties.

FoundationStackProps

Name	Type	Required	Description
environment	`string`	Yes	Environment label used in the OIDC subject (e.g., `test`, `production`).

Resources Created

Resource	Description
OpenID Connect Provider	`iam.OpenIdConnectProvider` for `token.actions.githubusercontent.com` with client ID `sts.amazonaws.com`.
IAM Role	Named `GitHubActionsServiceRole` by default (or override via `GITHUB_DEPLOY_ROLE` env var). Trusts GitHub OIDC with subject: `repo:<owner>/<repo>:environment:<ENV>`.
Toolkit Cleaner	`ToolkitCleaner` from `cloudstructs` to automatically clean up old CDK assets.

Deployment Behavior

Only synthesized when not running a branch deployment (guarded by if (!process.env.GIT_BRANCH_REF) in src/main.ts).
Deploy once per AWS account/region to enable OIDC deployments.

Usage

# Deploy Foundation + Starter stacks for test env
npm run test:deploy:all

# Or deploy just the FoundationStack
npm run test:deploy:stack FoundationStack

StarterStack

Source: src/stacks/starter-stack.ts

Your application entry stack — add constructs and resources here. Shows a commented example using NetworkConstruct for a secure VPC.

Initializers

new StarterStack(scope: Construct, id: string, props?: StarterStackProps)

Parameters

Name	Type	Description
scope	`Construct`	The scope in which to define this stack.
id	`string`	The scoped stack ID.
props	`StarterStackProps` (optional)	Stack configuration properties.

StarterStackProps

Name	Type	Required	Description
environment	`string`	No	Used for tagging and resource naming in `src/main.ts`.

Usage

# Synthesize and diff only the starter stack
npm run test:synth
npm run test:diff:stack StarterStack

# Deploy only the starter stack
npm run test:deploy:stack StarterStack

Generated npm scripts

Generated from .projenrc.ts for environment configs: test (branch deploys enabled) and production (branch deploys disabled).

Test Environment (Regular)

Script	Description
`test:synth`	Synthesize all stacks
`test:ls`	List all stacks
`test:deploy:all`	Deploy all stacks
`test:deploy:stack <StackName>`	Deploy specific stack
`test:destroy:all`	Destroy all stacks
`test:destroy:stack <StackName>`	Destroy specific stack
`test:diff:all`	Show diff for all stacks
`test:diff:stack <StackName>`	Show diff for specific stack

Test Environment (Branch)

Script	Description
`test:branch:synth`	Synthesize all branch stacks
`test:branch:ls`	List all branch stacks
`test:branch:deploy:all`	Deploy all branch stacks
`test:branch:deploy:stack <StackName>`	Deploy specific branch stack
`test:branch:destroy:all`	Destroy all branch stacks
`test:branch:destroy:stack <StackName>`	Destroy specific branch stack
`test:branch:diff:all`	Show diff for all branch stacks
`test:branch:diff:stack <StackName>`	Show diff for specific branch stack

Production Environment

Script	Description
`production:synth`	Synthesize all stacks
`production:ls`	List all stacks
`production:deploy:all`	Deploy all stacks
`production:deploy:stack <StackName>`	Deploy specific stack
`production:destroy:all`	Destroy all stacks
`production:destroy:stack <StackName>`	Destroy specific stack
`production:diff:all`	Show diff for all stacks
`production:diff:stack <StackName>`	Show diff for specific stack

Notes

:all operates on all stacks in the app; :stack accepts stack names as args.
Branch tasks inject GIT_BRANCH_REF automatically (from git rev-parse --abbrev-ref HEAD) for safe name suffixing and isolation.
The FoundationStack is excluded from branch deploys by design.