Stacks

Overview

The starter kit includes two stacks: FoundationStack for OIDC and tooling setup, and StarterStack for your application resources. Projen generates npm scripts for each environment.

Learn how to create AWS CDK stacks before exploring these patterns.

FoundationStack

Source: src/stacks/foundation-stack.ts

Sets up GitHub OpenID Connect (OIDC) and an IAM role for GitHub Actions deployments. Also adds a CloudFormation Toolkit cleaner to remove old CDK assets.

Constructor

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

FoundationStackProps

Resources created

Deployment behavior

• Excluded from branch deployments - guarded by if (!process.env.GIT_BRANCH_REF) in src/main.ts
• Deploy once per account/region - enables OIDC deployments for that environment
• Creates GitHub environment link - IAM role subject matches GitHub environment name

Usage

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

# Deploy only FoundationStack
npm run test:deploy:stack FoundationStack

StarterStack

Source: src/stacks/starter-stack.ts

Your application entry stack. Add constructs and resources here. Includes a commented example using NetworkConstruct for a secure VPC.

Constructor

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

StarterStackProps

Usage

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

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

# Branch deployment
npm run test:branch:deploy:stack StarterStack

Adding resources

// src/stacks/starter-stack.ts
import * as cdk from 'aws-cdk-lib';
import * as s3 from 'aws-cdk-lib/aws-s3';
import { Construct } from 'constructs';

export class StarterStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    new s3.Bucket(this, 'DataBucket', {
      blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
      encryption: s3.BucketEncryption.S3_MANAGED,
    });
  }
}

Generated npm scripts

Projen generates scripts for each environment defined in .projenrc.ts. The examples below assume test (with branch deploys enabled) and production (branch deploys disabled).

Test environment (regular)

Test environment (branch)

Production environment

Script behavior

• :all scripts operate on all stacks in the app
• :stack scripts accept stack names as arguments
• Branch tasks automatically inject GIT_BRANCH_REF from current git branch
• FoundationStack is excluded from branch deploys by design

Adding a new stack

1. Create the stack file:

// src/stacks/app-stack.ts
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';

export class AppStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);
    // Add resources
  }
}

2. Export from index:

// src/stacks/index.ts
export { FoundationStack } from './foundation-stack';
export { StarterStack } from './starter-stack';
export { AppStack } from './app-stack';

3. Instantiate in src/main.ts:

import { AppStack } from './stacks';

new AppStack(app, createEnvResourceName('AppStack'), { env: awsAccountConfig });

4. Verify:

npm run test:synth
npm run test:ls

Next steps

• Constructs - Building blocks for stacks
• Helpers - How scripts are generated
• Usage Examples - Common stack patterns