Skip to content

Setting up a project with Projen

Projen is a tool that helps define and maintain complex project configurations through code. It allows you to generate project configuration files from a well-typed definition, making it easier to manage and maintain your project structure.

Prerequisites

Before getting started, ensure that you have the following prerequisites installed:

  • Node.js (version 16.x or later)
  • npm (comes bundled with Node.js)

Projen doesn't need to be installed separately. You will be using npx to run Projen, which takes care of all the required setup steps.

Step 1: Initialize a new project

Follow these steps to initialize a new project using Projen:

  1. Open your terminal or command prompt.
  2. Navigate to the directory where you want to create your new project.
  3. Run the following command to initialize a new CDK CI/CD Wrapper project:
npx projen@latest new awscdk-app-ts --no-git --deps @cdklabs/cdk-cicd-wrapper-projen

This command initializes a new AWS CDK TypeScript app project with the @cdklabs/cdk-cicd-wrapper-projen dependency.

  1. Open the .projenrc.ts file and add the following code:
import { awscdk } from 'projen';
import { CdkCICDWrapper } from '@cdklabs/cdk-cicd-wrapper-projen';

const project = new awscdk.AwsCdkTypeScriptApp({
  cdkVersion: '2.1.0',
  defaultReleaseBranch: 'main',
  deps: ['@cdklabs/cdk-cicd-wrapper'],
  name: 'project',
  projenrcTs: true,
});

//@ts-ignore Projen Versions can be different during the upgrade process and would resolve complains about assignability issues.
new CdkCICDWrapper(project, {
  cdkQualifier: 'wrapper',
  repositoryName: 'projen-sample-wrapper',
  repositoryType: 'CODECOMMIT',
});

project.synth();

This code configures the project with the necessary settings for the AWS CDK and the CdkCICDWrapper component.

  1. Execute the npx projen command to enable the project.

  2. Before deploying, run the following commands to ensure your project is ready:

npm run validate -- --fix
npm run license -- --fix
  • npm run validate -- --fix will create the required package-verification.json file for you.
  • npm run license -- --fix will generate a valid Notice file for you.

Step 2: Configure stacks

The PipelineBlueprint component provided by the {{ npm_pipeline }} package allows you to define and configure the stacks for your application. Here's an example of how you can configure your stacks:

import * as cdk from 'aws-cdk-lib';
import { PipelineBlueprint } from '@cdklabs/cdk-cicd-wrapper';

const app = new cdk.App();

PipelineBlueprint.builder().addStack({
  provide: (context) => {
    // Create your stacks here
    new YourStack(context.scope, `${context.blueprintProps.applicationName}YourStack`, {
      applicationName: context.blueprintProps.applicationName,
      stageName: context.stage,
    });
    new YourOtherStack(context.scope, `${context.blueprintProps.applicationName}YourOtherStack`, {
      applicationQualifier: context.blueprintProps.applicationQualifier,
      encryptionKey: context.get(GlobalResources.Encryption)!.kmsKey,
    });
  }
}).synth(app);

Note: Refer to the Developer Guide for more information on the PipelineBlueprint component and how to configure your stacks.

Step 3: Configure environment variables / create .env file

The CDK CI/CD Wrapper uses environment variables to store sensitive information and configuration settings. The CdkCICDWrapper component creates a sample .env file in the root directory of your project and defines the necessary variables there. You must fill out the values for these variables.

This file is created once, and you must maintain it manually as needed.

Step 4: Bootstrap your stages

The CDK CI/CD Wrapper uses the AWS CDK Toolkit with a cross-account trust relationship to deploy to multiple AWS accounts. This bootstrapping process must be established for each stage, and each account must have a trust relationship with the RES account.

If you are reusing an existing CDK bootstrapping setup, you can skip this step. Otherwise, follow these instructions to bootstrap your stages:

  1. Prepare the RES stage:
npm run bootstrap RES
  1. Prepare the DEV stage:
npm run bootstrap DEV
  1. Prepare the INT stage:
npm run bootstrap INT
  1. Prepare the PROD stage:
npm run bootstrap PROD

Note: The stages have to be defined in the .projenrc.ts file CdkCICDWrapperOptions.stages variable.

Step 5: Deploy the pipeline

Once you have completed the previous steps, you can deploy the pipeline:

  1. In your terminal or command prompt, navigate to the root directory of your project.
  2. Run the following command to deploy the pipeline:
npm run deploy

This command will prompt you to confirm the deployment and then create the necessary resources for your pipeline in AWS.

Step 6: Push your changes to the git repository

After the deployment is complete, Projen will automatically trigger the pipeline and begin the process of building, testing, and deploying your application infrastructure based on the defined stages. Push your changes to the Git repository to start the pipeline process.

Conclusion

Congratulations! You have successfully set up a project with Projen and configured a pipeline for building and deploying your cloud-based application infrastructure. This documentation provides an overview of the process and guides you through the necessary steps.

If you need further assistance or have any questions, please refer to the official Projen documentation or reach out to the project maintainers for support.