{"id":19396460,"url":"https://github.com/tmokmss/deploy-time-build","last_synced_at":"2026-02-24T09:12:27.410Z","repository":{"id":49927054,"uuid":"491558744","full_name":"tmokmss/deploy-time-build","owner":"tmokmss","description":"Run build on CDK deployment time","archived":false,"fork":false,"pushed_at":"2026-01-27T09:46:17.000Z","size":33108,"stargazers_count":50,"open_issues_count":6,"forks_count":9,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-27T22:21:44.952Z","etag":null,"topics":["aws","cdk"],"latest_commit_sha":null,"homepage":"https://constructs.dev/packages/deploy-time-build/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tmokmss.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":"2022-05-12T14:57:16.000Z","updated_at":"2026-01-27T09:43:28.000Z","dependencies_parsed_at":"2024-06-21T13:09:57.912Z","dependency_job_id":"cdfe960d-6888-4d5c-babf-ae0e4773b7f6","html_url":"https://github.com/tmokmss/deploy-time-build","commit_stats":{"total_commits":28,"total_committers":2,"mean_commits":14.0,"dds":0.0357142857142857,"last_synced_commit":"545d7f93ad8eb05efeac4058d20939d107b611cb"},"previous_names":[],"tags_count":76,"template":false,"template_full_name":null,"purl":"pkg:github/tmokmss/deploy-time-build","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmokmss%2Fdeploy-time-build","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmokmss%2Fdeploy-time-build/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmokmss%2Fdeploy-time-build/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmokmss%2Fdeploy-time-build/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tmokmss","download_url":"https://codeload.github.com/tmokmss/deploy-time-build/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmokmss%2Fdeploy-time-build/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29777829,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-24T04:54:30.205Z","status":"ssl_error","status_checked_at":"2026-02-24T04:53:58.628Z","response_time":75,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["aws","cdk"],"created_at":"2024-11-10T10:35:25.606Z","updated_at":"2026-02-24T09:12:27.387Z","avatar_url":"https://github.com/tmokmss.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## Usage\nInstall from npm:\n\n```sh\nnpm i 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 'deploy-time-build';\n\ndeclare const api: apigateway.RestApi;\ndeclare const destinationBucket: s3.IBucket;\ndeclare const distribution: cloudfront.IDistribution;\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` using a [`s3-deployment.BucketDeployment`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_deployment.BucketDeployment.html) construct.\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\nassets: [\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```\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\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\ndeclare const build: NodejsBuild;\niam.Grant.addToPrincipal({ grantee: build, actions: ['s3:ListBucket'], resources:['*'] })\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#### 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\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```\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 '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 `SociIndexBuild` construct.\n\n![soci-architecture](imgs/soci-architecture.png)\n\nThe following code is an example to use the construct:\n\n```ts\nimport { SociIndexBuild } from 'deploy-time-build';\n\nconst asset = new DockerImageAsset(this, 'Image', { directory: 'example-image' });\nnew SociIndexBuild(this, 'Index', { imageTag: asset.assetHash, repository: asset.repository });\n// or using a utility method\nSociIndexBuild.fromDockerImageAsset(this, 'Index2', asset);\n\n// Use the asset for ECS Fargate tasks\nimport { AssetImage } from 'aws-cdk-lib/aws-ecs';\nconst assetImage = AssetImage.fromDockerImageAsset(asset);\n```\n\nWe currently use [`soci-wrapper`](https://github.com/tmokmss/soci-wrapper) to build and push SOCI indices.\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%2Ftmokmss%2Fdeploy-time-build","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftmokmss%2Fdeploy-time-build","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmokmss%2Fdeploy-time-build/lists"}