Deploy-time Build

AWS CDK L3 construct that allows you to run a build job for specific purposes. Currently this library supports the following use cases:

• Build web frontend static files
• Build a container image
• Build Seekable OCI (SOCI) indices for container images

Usage

Install from npm:

npm i @cdklabs/deploy-time-build

This library defines several L3 constructs for specific use cases. Here is the usage for each case.

Build Node.js apps

You can build a Node.js app such as a React frontend app on deploy time by the NodejsBuild construct.

The following code is an example to use the construct:

from cdklabs.deploy_time_build import NodejsBuild


NodejsBuild(self, "ExampleBuild",
    assets=[AssetConfig(
        path="example-app",
        exclude=["dist", "node_modules"]
    )
    ],
    destination_bucket=destination_bucket,
    distribution=distribution,
    output_source_directory="dist",
    build_commands=["npm ci", "npm run build"],
    build_environment={
        "VITE_API_ENDPOINT": api.url
    },
    nodejs_version=24
)

Note that it is possible to pass environment variable VITE_API_ENDPOINT: api.url to the construct, which is resolved on deploy time, and injected to the build environment (a vite process in this case.) The resulting build artifacts will be deployed to destinationBucket from CodeBuild.

You can specify multiple input assets by assets property. These assets are extracted to respective sub directories. For example, assume you specified assets like the following:

NodejsBuild(self, "ExampleBuild",
    assets=[AssetConfig(
        # directory containing source code and package.json
        path="example-app",
        exclude=["dist", "node_modules"],
        commands=["npm install"]
    ), AssetConfig(
        # directory that is also required for the build
        path="module1"
    )
    ],
    destination_bucket=destination_bucket,
    distribution=distribution,
    output_source_directory="dist",
    nodejs_version=24
)

Then, the extracted directories will be located as the following:

.                         # a temporary directory (automatically created)
├── example-app           # extracted example-app assets
│   ├── src/              # dist or node_modules directories are excluded even if they exist locally.
│   ├── package.json      # npm install will be executed since its specified in `commands` property.
│   └── package-lock.json
└── module1               # extracted module1 assets

You can also override the path where assets are extracted by extractPath property for each asset.

With outputEnvFile property enabled, a .env file is automatically generated and uploaded to your S3 bucket. This file can be used running you frontend project locally. You can download the file to your local machine by running the command added in the stack output.

Please also check the example directory for a complete example.

Allowing access from the build environment to other AWS resources

Since NodejsBuild construct implements iam.IGrantable interface, you can use grant* method of other constructs to allow access from the build environment.

# some_bucket: s3.IBucket
# build: NodejsBuild

some_bucket.grant_read_write(build)

You can also use iam.Grant class to allow any actions and resources.

# build: NodejsBuild

iam.Grant.add_to_principal(grantee=build, actions=["s3:ListBucket"], resource_arns=["*"])

Motivation - why do we need the NodejsBuild construct?

I talked about why this construct can be useful in some situations at CDK Day 2023. See the recording or slides below:

Recording | Slides

Caching

You can enable npm caching to speed up builds using the cache property:

NodejsBuild(self, "ExampleBuild",
    assets=[AssetConfig(
        path="example-app",
        exclude=["dist", "node_modules"]
    )
    ],
    destination_bucket=destination_bucket,
    output_source_directory="dist",
    cache=CacheType.S3,  # or CacheType.LOCAL
    nodejs_version=24
)

Two cache types are available:

• CacheType.S3: Stores the npm cache directory in an S3 bucket. Good for builds that run infrequently on different hosts.
• CacheType.LOCAL: Stores the npm cache directory on the build host. Faster than S3 but only effective if builds run on the same host.

Compute Type

You can specify the compute type for the CodeBuild project using the computeType property:

NodejsBuild(self, "ExampleBuild",
    assets=[AssetConfig(
        path="example-app",
        exclude=["dist", "node_modules"]
    )
    ],
    destination_bucket=destination_bucket,
    output_source_directory="dist",
    compute_type=ComputeType.MEDIUM,
    nodejs_version=24
)

Considerations

Since this construct builds your frontend apps every time you deploy the stack and there is any change in input assets (and currently there's even no build cache in the Lambda function!), the time a deployment takes tends to be longer (e.g. a few minutes even for the simple app in example directory.) This might results in worse developer experience if you want to deploy changes frequently (imagine cdk watch deployment always re-build your frontend app).

To mitigate this issue, you can separate the stack for frontend construct from other stacks especially for a dev environment. Another solution would be to set a fixed string as an asset hash, and avoid builds on every deployment.

NodejsBuild(self, "ExampleBuild",
    assets=[AssetConfig(
        path="../frontend",
        exclude=["node_modules", "dist"],
        commands=["npm ci"],
        # Set a fixed string as a asset hash to prevent deploying changes.
        # This can be useful for an environment you use to develop locally.
        asset_hash="frontend_asset"
    )
    ],
    destination_bucket=destination_bucket,
    distribution=distribution,
    output_source_directory="dist",
    nodejs_version=24
)

Build a container image

You can build a container image at deploy time by the following code:

from aws_cdk.aws_ecs import RuntimePlatform
from cdklabs.deploy_time_build import ContainerImageBuild


image = ContainerImageBuild(self, "Build",
    directory="example-image",
    build_args={"DUMMY_FILE_SIZE_MB": "15"},
    tag="my-image-tag"
)
DockerImageFunction(self, "Function",
    code=image.to_lambda_docker_image_code()
)
arm_image = ContainerImageBuild(self, "BuildArm",
    directory="example-image",
    platform=Platform.LINUX_ARM64,
    repository=image.repository,
    zstd_compression=True
)
FargateTaskDefinition(self, "TaskDefinition",
    runtime_platform=RuntimePlatform(cpu_architecture=CpuArchitecture.ARM64)
).add_container("main",
    image=arm_image.to_ecs_docker_image_code()
)

The third argument (props) are a superset of DockerImageAsset's properties. You can set a few additional properties such as tag, repository, and zstdCompression.

Build SOCI index for a container image

Seekable OCI (SOCI) is a way to help start tasks faster for Amazon ECS tasks on Fargate 1.4.0. You can build and push a SOCI index using the SociIndexV2Build construct.

The following code is an example to use the construct:

from cdklabs.deploy_time_build import SociIndexV2Build


asset = DockerImageAsset(self, "Image", directory="example-image")
soci_index = SociIndexV2Build(self, "SociV2Index",
    repository=asset.repository,
    input_image_tag=asset.asset_hash,
    output_image_tag=f"{asset.assetHash}-soci"
)

# Use with ECS Fargate
task_definition = FargateTaskDefinition(self, "TaskDefinition")
task_definition.add_container("main",
    image=soci_index.to_ecs_docker_image_code()
)

# Or create from DockerImageAsset using utility method
soci_index_from_asset = SociIndexV2Build.from_docker_image_asset(self, "SociV2Index2", asset)

The SociIndexV2Build construct:

• Takes an input container image and builds a SOCI v2 index for it
• Outputs a new image tag with the embedded SOCI index
• Provides toEcsDockerImageCode() method to easily use with ECS tasks
• Uses the same ECR repository for input and output images

We currently use soci-wrapper to build and push SOCI indices.

Motivation - why do we need the SociIndexBuild construct?

Currently there are several other ways to build a SOCI index; 1. use soci-snapshotter CLI, or 2. use cfn-ecr-aws-soci-index-builder solution, none of which can be directly used from AWS CDK. If you are familiar with CDK, you should often deploy container images as CDK assets, which is an ideal way to integrate with other L2 constructs such as ECS. To make the developer experience for SOCI as close as the ordinary container images, the SociIndexBuild allows you to deploying a SOCI index directly from CDK, without any dependencies outside of CDK context.

Development

Commands for maintainers:

# run test locally
npx tsc -p tsconfig.dev.json
npx integ-runner
npx integ-runner --update-on-failed