{"id":37023208,"url":"https://github.com/cdklabs/deploy-time-build","last_synced_at":"2026-02-19T06:05:33.456Z","repository":{"id":325677514,"uuid":"1101389191","full_name":"cdklabs/deploy-time-build","owner":"cdklabs","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-07T12:59:13.000Z","size":456,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-07T13:23:31.885Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cdklabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-21T15:51:40.000Z","updated_at":"2026-01-07T12:59:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cdklabs/deploy-time-build","commit_stats":null,"previous_names":["cdklabs/deploy-time-build"],"tags_count":0,"template":false,"template_full_name":"amazon-archives/__template_Apache-2.0","purl":"pkg:github/cdklabs/deploy-time-build","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdklabs%2Fdeploy-time-build","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdklabs%2Fdeploy-time-build/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdklabs%2Fdeploy-time-build/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdklabs%2Fdeploy-time-build/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cdklabs","download_url":"https://codeload.github.com/cdklabs/deploy-time-build/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdklabs%2Fdeploy-time-build/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28408737,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T01:52:23.358Z","status":"online","status_checked_at":"2026-01-14T02:00:06.678Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-14T02:46:57.466Z","updated_at":"2026-02-19T06:05:33.449Z","avatar_url":"https://github.com/cdklabs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Deploy-time Build\nAWS CDK L3 construct that allows you to run a build job for specific purposes. Currently this library supports the following use cases:\n\n* Build web frontend static files\n* Build a container image\n* Build Seekable OCI (SOCI) indices for container images\n\n[![View on Construct Hub](https://constructs.dev/badge?package=%40cdklabs%2Fdeploy-time-build)](https://constructs.dev/packages/@cdklabs/deploy-time-build)\n\n## Usage\nInstall from npm:\n\n```sh\nnpm i @cdklabs/deploy-time-build\n```\n\nThis library defines several L3 constructs for specific use cases. Here is the usage for each case.\n\n### Build Node.js apps\n\nYou can build a Node.js app such as a React frontend app on deploy time by the `NodejsBuild` construct.\n\n![architecture](./imgs/architecture.png)\n\nThe following code is an example to use the construct:\n\n```ts\nimport { NodejsBuild } from '@cdklabs/deploy-time-build';\n\nnew NodejsBuild(this, 'ExampleBuild', {\n    assets: [\n        {\n            path: 'example-app',\n            exclude: ['dist', 'node_modules'],\n        },\n    ],\n    destinationBucket,\n    distribution,\n    outputSourceDirectory: 'dist',\n    buildCommands: ['npm ci', 'npm run build'],\n    buildEnvironment: {\n        VITE_API_ENDPOINT: api.url,\n    },\n});\n```\n\nNote 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.)\nThe resulting build artifacts will be deployed to `destinationBucket` from CodeBuild.\n\nYou 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:\n\n```ts fixture=imported\nnew NodejsBuild(this, 'ExampleBuild', {\n    assets: [\n        {\n            // directory containing source code and package.json\n            path: 'example-app',\n            exclude: ['dist', 'node_modules'],\n            commands: ['npm install'],\n        },\n        {\n            // directory that is also required for the build\n            path: 'module1',\n        },\n    ],\n    destinationBucket,\n    distribution,\n    outputSourceDirectory: 'dist',\n});\n```\n\nThen, the extracted directories will be located as the following:\n\n```sh\n.                         # a temporary directory (automatically created)\n├── example-app           # extracted example-app assets\n│   ├── src/              # dist or node_modules directories are excluded even if they exist locally.\n│   ├── package.json      # npm install will be executed since its specified in `commands` property.\n│   └── package-lock.json\n└── module1               # extracted module1 assets\n```\n\nYou can also override the path where assets are extracted by `extractPath` property for each asset.\n\nWith `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.\n\nPlease also check [the example directory](./example/) for a complete example. \n\n#### Allowing access from the build environment to other AWS resources\nSince `NodejsBuild` construct implements [`iam.IGrantable`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IGrantable.html) interface, you can use `grant*` method of other constructs to allow access from the build environment.\n\n```ts fixture=imported\ndeclare const someBucket: s3.IBucket;\ndeclare const build: NodejsBuild;\nsomeBucket.grantReadWrite(build);\n```\n\nYou can also use [`iam.Grant`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Grant.html) class to allow any actions and resources.\n\n```ts fixture=imported\ndeclare const build: NodejsBuild;\niam.Grant.addToPrincipal({ grantee: build, actions: ['s3:ListBucket'], resourceArns:['*'] })\n```\n\n#### Motivation - why do we need the `NodejsBuild` construct?\nI talked about why this construct can be useful in some situations at CDK Day 2023. See the recording or slides below:\n\n[Recording](https://www.youtube.com/live/b-nSH18gFQk?si=ogEZ2x1NixOj6J6j\u0026t=373) | [Slides](https://speakerdeck.com/tmokmss/deploy-web-frontend-apps-with-aws-cdk)\n\n#### Caching\n\nYou can enable npm caching to speed up builds using the `cache` property:\n\n```ts fixture=imported\nnew NodejsBuild(this, 'ExampleBuild', {\n    assets: [\n        {\n            path: 'example-app',\n            exclude: ['dist', 'node_modules'],\n        },\n    ],\n    destinationBucket,\n    outputSourceDirectory: 'dist',\n    cache: CacheType.S3, // or CacheType.LOCAL\n});\n```\n\nTwo cache types are available:\n- `CacheType.S3`: Stores the npm cache directory in an S3 bucket. Good for builds that run infrequently on different hosts.\n- `CacheType.LOCAL`: Stores the npm cache directory on the build host. Faster than S3 but only effective if builds run on the same host.\n\n#### Compute Type\n\nYou can specify the compute type for the CodeBuild project using the `computeType` property:\n\n```ts fixture=imported\nnew NodejsBuild(this, 'ExampleBuild', {\n    assets: [\n        {\n            path: 'example-app',\n            exclude: ['dist', 'node_modules'],\n        },\n    ],\n    destinationBucket,\n    outputSourceDirectory: 'dist',\n    computeType: ComputeType.MEDIUM,\n});\n```\n\n#### Considerations\nSince 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).\n\nTo 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.\n\n```ts fixture=imported\nnew NodejsBuild(this, 'ExampleBuild', {\n    assets: [\n        {\n            path: '../frontend',\n            exclude: ['node_modules', 'dist'],\n            commands: ['npm ci'],\n            // Set a fixed string as a asset hash to prevent deploying changes.\n            // This can be useful for an environment you use to develop locally.\n            assetHash: 'frontend_asset',\n        },\n    ],\n    destinationBucket,\n    distribution,\n    outputSourceDirectory: 'dist',\n});\n```\n\n### Build a container image\nYou can build a container image at deploy time by the following code:\n\n```ts\nimport { ContainerImageBuild } from '@cdklabs/deploy-time-build';\n\nconst image = new ContainerImageBuild(this, 'Build', { \n    directory: 'example-image', \n    buildArgs: { DUMMY_FILE_SIZE_MB: '15' },\n    tag: 'my-image-tag',\n});\nnew DockerImageFunction(this, 'Function', {\n    code: image.toLambdaDockerImageCode(),\n});\nconst armImage = new ContainerImageBuild(this, 'BuildArm', {\n    directory: 'example-image',\n    platform: Platform.LINUX_ARM64,\n    repository: image.repository,\n    zstdCompression: true,\n});\nnew FargateTaskDefinition(this, 'TaskDefinition', { \n    runtimePlatform: { cpuArchitecture: CpuArchitecture.ARM64 } \n}).addContainer('main', {\n    image: armImage.toEcsDockerImageCode(),\n});\n```\n\nThe third argument (props) are a superset of DockerImageAsset's properties. You can set a few additional properties such as `tag`, `repository`, and `zstdCompression`.\n\n### Build SOCI index for a container image\n[Seekable OCI (SOCI)](https://aws.amazon.com/about-aws/whats-new/2022/09/introducing-seekable-oci-lazy-loading-container-images/) 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.\n\n![soci-architecture](imgs/soci-architecture.png)\n\nThe following code is an example to use the construct:\n\n```ts\nimport { SociIndexV2Build } from '@cdklabs/deploy-time-build';\n\nconst asset = new DockerImageAsset(this, 'Image', { directory: 'example-image' });\nconst sociIndex = new SociIndexV2Build(this, 'SociV2Index', {\n  repository: asset.repository,\n  inputImageTag: asset.assetHash,\n  outputImageTag: `${asset.assetHash}-soci`,\n});\n\n// Use with ECS Fargate\nconst taskDefinition = new FargateTaskDefinition(this, 'TaskDefinition');\ntaskDefinition.addContainer('main', {\n  image: sociIndex.toEcsDockerImageCode(),\n});\n\n// Or create from DockerImageAsset using utility method\nconst sociIndexFromAsset = SociIndexV2Build.fromDockerImageAsset(this, 'SociV2Index2', asset);\n```\n\nThe `SociIndexV2Build` construct:\n- Takes an input container image and builds a SOCI v2 index for it\n- Outputs a new image tag with the embedded SOCI index\n- Provides `toEcsDockerImageCode()` method to easily use with ECS tasks\n- Uses the same ECR repository for input and output images\n\nWe currently use [`soci-wrapper`](https://github.com/tmokmss/soci-wrapper) to build and push SOCI indices.\n\n\u003e [!WARNING]\n\u003e The previous `SocideIndexBuild` construct is now deprecated. Customers new to SOCI on AWS Fargate can only use SOCI index manifest v2. See [this article](https://aws.amazon.com/blogs/containers/improving-amazon-ecs-deployment-consistency-with-soci-index-manifest-v2/) for more details.\n\n#### Motivation - why do we need the `SociIndexBuild` construct?\n\nCurrently there are several other ways to build a SOCI index; 1. use `soci-snapshotter` CLI, or 2. use [cfn-ecr-aws-soci-index-builder](https://github.com/aws-ia/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.\n\n## Development\nCommands for maintainers:\n\n```sh\n# run test locally\nnpx tsc -p tsconfig.dev.json\nnpx integ-runner\nnpx integ-runner --update-on-failed\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcdklabs%2Fdeploy-time-build","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcdklabs%2Fdeploy-time-build","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcdklabs%2Fdeploy-time-build/lists"}