CDK App Project¶

The CDK App Project type provides an opinionated setup for creating AWS CDK applications with best practices and common configurations pre-configured.

Overview¶

This project type extends the standard AwsCdkTypeScriptApp from projen with additional features:

Prettier configuration with sensible defaults
VSCode settings and extensions for enhanced development experience
Common project structure and tooling setup
Configurable options that respect user preferences
CDK app-specific setup with sample application code

Quick Start¶

To create a new CDK App project, use the projen CLI:

npx projen new --from @jttc/projen-project-types cdk-app

This command will create a new project with the CDK App template and prompt you for the required configuration options such as:

Project name
CDK version
Default branch

After the project is created, you can customize it further by editing the .projenrc.ts file:

.projenrc.ts
import { CdkApp } from '@jttc/projen-project-types';

const project = new CdkApp({
  name: 'my-awesome-cdk-app',
  defaultReleaseBranch: 'main',
  cdkVersion: '2.1.0',

  // Add any additional customizations here
  prettier: true,
  vscode: true,
});

project.synth();

Highlighted lines explanation:

Line 4: Choose a descriptive name for your CDK application
Line 6: Pin to a specific CDK version for consistency
Line 10: Enable prettier formatting (default: true)
Line 11: Enable VSCode workspace configuration (default: true)

Features¶

Common Configurations¶

This project type includes the same common configurations as other project types:

Default Configurations

For complete details about Prettier and VSCode configurations, see Default Configurations. This includes:

Prettier Configuration - Code formatting rules and customization
VSCode Configuration - Editor settings and recommended extensions

CDK App Structure¶

The CDK App project creates a complete application structure with:

Main application entry point (src/main.ts)
CDK configuration (cdk.json)
Sample stack (optional via sampleCode option)
Deployment scripts and configuration
Proper TypeScript setup for CDK apps

Configuration Options¶

Basic Configuration¶

All standard AwsCdkTypeScriptAppOptions are supported. Here are the most common options:

Basic CDK App Configuration
const project = new CdkApp({
  // Required options
  name: 'my-cdk-app',
  cdkVersion: '2.1.0',
  defaultReleaseBranch: 'main',

  // Optional configurations (see sections below)
});

Common Configuration Options¶

For Prettier and VSCode configuration options, refer to Default Configurations:

Prettier: Customization Guide
VSCode: Configuration Options

Sample Code Configuration¶

Enable/Disable Sample Code¶

Default Behavior (Enabled)Disable Sample Code

Sample Code Enabled by Default
const project = new CdkApp({
  // ... other options
  // sampleCode: undefined (defaults to enabled)
});

Disable Sample Code
const project = new CdkApp({
  // ... other options
  sampleCode: false,
});

Highlighted line explanation:

Line 3: No sample application code will be generated

Behavior Matrix¶

`prettier`	`vscode`	`sampleCode`	Prettier Files	VSCode Files	Sample App Code
`undefined`	`undefined`	`undefined`	✅ Created	✅ Created	✅ Generated
`true`	`true`	`true`	✅ Created	✅ Created	✅ Generated
`false`	`true`	`false`	❌ Not created	✅ Created	❌ No sample
`true`	`false`	`true`	✅ Created	❌ Not created	✅ Generated
`false`	`false`	`false`	❌ Not created	❌ Not created	❌ No sample

Examples¶

Minimal Setup¶

Perfect for getting started quickly with all defaults:

.projenrc.ts - Minimal Setup
import { CdkApp } from '@jttc/projen-project-types';

const project = new CdkApp({
  name: 'simple-cdk-app',
  cdkVersion: '2.1.0',
  defaultReleaseBranch: 'main',
  // All other options use sensible defaults
});

project.synth();

Customized Setup¶

Example with custom prettier settings and disabled sample code:

.projenrc.ts - Advanced Configuration
import { CdkApp } from '@jttc/projen-project-types';

const project = new CdkApp({
  name: 'advanced-cdk-app',
  cdkVersion: '2.1.0',
  defaultReleaseBranch: 'main',

  // Custom prettier settings
  prettierOptions: {
    settings: {
      printWidth: 120,
      tabWidth: 4,
    },
  },

  // Enable VSCode (explicit)
  vscode: true,

  // Disable sample code for clean start
  sampleCode: false,

  // Additional CDK app options
  context: {
    '@aws-cdk/aws-lambda:recognizeLayerVersion': true,
  },
});

project.synth();

Highlighted lines explanation:

Lines 8-13: Custom prettier settings for longer lines and 4-space indentation
Line 16: Enable VSCode configuration explicitly
Line 19: Disable sample code generation for a clean starting point

Production Setup¶

Optimized for production deployments:

.projenrc.ts - Production Configuration
import { CdkApp } from '@jttc/projen-project-types';

const project = new CdkApp({
  name: 'production-cdk-app',
  cdkVersion: '2.1.0', 
  defaultReleaseBranch: 'main',

  // Production-optimized settings
  sampleCode: false,
  prettier: true,
  vscode: true,

  // CDK context for production features
  context: {
    '@aws-cdk/core:enableStackNameDuplicates': true,
    '@aws-cdk/core:stackRelativeExports': true,
  },

  // Dependencies for common production patterns
  deps: [
    '@aws-cdk/aws-lambda',
    '@aws-cdk/aws-apigateway', 
    '@aws-cdk/aws-dynamodb',
  ],
});

project.synth();

Highlighted lines explanation:

Line 9: No sample code for production applications
Lines 10-11: Keep development tools enabled
Lines 14-17: CDK feature flags for production deployments

Project Structure¶

After running yarn projen with a CDK App project, you'll get the following structure:

Generated Project Structure

my-cdk-app/
├── .github/
│   └── workflows/              # CI/CD workflows
│       ├── build.yml
│       └── upgrade-main.yml
├── .vscode/                    # VSCode configuration (if enabled)
│   ├── extensions.json         # Recommended extensions
│   └── settings.json          # Editor settings
├── src/
│   └── main.ts                # Application entry point (if sampleCode enabled)
├── test/
│   └── *.test.ts              # Test files
├── .eslintrc.json             # ESLint configuration
├── .gitignore                 # Git ignore rules
├── .prettierrc.json           # Prettier config (if enabled)
├── .projenrc.ts              # Projen configuration
├── cdk.json                  # CDK configuration
├── package.json              # NPM package configuration
├── tsconfig.json             # TypeScript configuration
└── README.md                 # Generated README

Conditional Files

Some files are only created based on your configuration:

.vscode/ folder: Only when vscode: true (default)
.prettierrc.json: Only when prettier: true (default)
src/main.ts: Only when sampleCode: true (default)

Deployment¶

Local Development¶

For local development and testing:

# Install dependencies
yarn install

# Build the project
yarn build

# Synthesize CloudFormation templates
npx cdk synth

# Deploy to AWS (requires AWS credentials)
npx cdk deploy

CI/CD Pipeline¶

The generated GitHub Actions workflows provide automated:

Build and test on pull requests
Dependency updates with automated PRs
Security scanning with automated vulnerability detection

CDK Commands¶

Common CDK commands you'll use:

# List all stacks
npx cdk list

# Show differences before deployment
npx cdk diff

# Deploy specific stack
npx cdk deploy StackName

# Destroy stack
npx cdk destroy StackName

Best Practices¶

1. Use Consistent Configurations¶

Stick with the default prettier and VSCode configurations unless you have specific requirements. This ensures consistency across your team and projects.

2. Pin CDK Version¶

Always specify a specific CDK version to ensure consistent builds:

cdkVersion: '2.1.0', // Good - specific version
// cdkVersion: '^2.0.0', // Avoid - could lead to inconsistencies

3. Environment-Specific Configuration¶

Use CDK context for environment-specific settings:

context: {
  'myapp:environment': 'production',
  'myapp:region': 'us-east-1',
},

4. Leverage Sample Code for Learning¶

Keep sampleCode: true when learning CDK or starting new projects. Disable it for production applications.

5. Use Feature Flags¶

Enable CDK feature flags for better functionality:

context: {
  '@aws-cdk/core:enableStackNameDuplicates': true,
  '@aws-cdk/core:stackRelativeExports': true,
},

Troubleshooting¶

CDK Commands Not Working¶

If CDK commands fail:

Ensure AWS credentials are configured (aws configure)
Verify CDK is installed globally (npm install -g aws-cdk)
Bootstrap your AWS environment (npx cdk bootstrap)

Prettier Not Working¶

If prettier isn't formatting your code:

Ensure the prettier extension is installed in VSCode
Check that "editor.defaultFormatter": "esbenp.prettier-vscode" is in your VSCode settings
Verify .prettierrc.json exists in your project root

Build Errors¶

If you encounter build errors:

Run yarn install to ensure all dependencies are installed
Run yarn projen to regenerate configuration files
Check TypeScript errors with yarn build

Deployment Issues¶

Common deployment problems:

Missing permissions: Ensure your AWS credentials have sufficient permissions
Resource conflicts: Use unique resource names across environments
Stack limits: AWS has limits on resources per stack

Migration Guide¶

From Standard AwsCdkTypeScriptApp¶

To migrate from a standard AwsCdkTypeScriptApp to CdkApp:

Install the package: npm install @jttc/projen-project-types
Update your .projenrc.ts:

- import { AwsCdkTypeScriptApp } from 'projen/lib/awscdk';
+ import { CdkApp } from '@jttc/projen-project-types';

- const project = new AwsCdkTypeScriptApp({
+ const project = new CdkApp({
  // ... same options
});

Run yarn projen to regenerate files
Commit the changes

The migration is backward compatible - all existing options will continue to work.

Advanced Configuration¶

Custom CDK Context¶

Configure CDK behavior with context values:

Advanced CDK Context
const project = new CdkApp({
  name: 'advanced-app',
  cdkVersion: '2.1.0',
  context: {
    // Feature flags
    '@aws-cdk/core:enableStackNameDuplicates': true,
    '@aws-cdk/aws-lambda:recognizeLayerVersion': true,

    // Custom application context
    'myapp:database-name': 'production-db',
    'myapp:api-domain': 'api.example.com',
  },
});

Additional Dependencies¶

Add commonly used CDK modules:

Common CDK Dependencies
const project = new CdkApp({
  name: 'full-stack-app',
  cdkVersion: '2.1.0',
  deps: [
    // Core AWS services
    '@aws-cdk/aws-lambda',
    '@aws-cdk/aws-apigateway',
    '@aws-cdk/aws-dynamodb',
    '@aws-cdk/aws-s3',

    // Additional tools
    '@aws-cdk/aws-route53',
    '@aws-cdk/aws-certificatemanager',
    '@aws-cdk/aws-cloudfront',
  ],
});

Contributing¶

To contribute improvements to the CDK App project type:

Fork the repository
Make your changes
Add tests for new functionality
Update documentation
Submit a pull request

Support¶

If you encounter issues or have questions:

Check this documentation
Review existing GitHub issues
Create a new issue with detailed information
Tag the maintainers for urgent issues

This project type is maintained by Jump to the Cloud team.