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 steps of the setup.

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',
  taskfile: true,
});

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:

task prepare

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:

task bootstrap

Note: The stages have to be defined in the .env file in the STAGES_ENABLED 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:
task 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.