token-injectable-docker-builder 1.13.4 → 2.0.0

package/.jsii

@@ -8536,7 +8536,7 @@
   },
   "name": "token-injectable-docker-builder",
   "readme": {
-    "markdown": "# TokenInjectableDockerBuilder\n\nThe `TokenInjectableDockerBuilder` is a flexible AWS CDK construct that enables the usage of AWS CDK tokens in the building, pushing, and deployment of Docker images to Amazon Elastic Container Registry (ECR). It leverages AWS CodeBuild and Lambda custom resources.\n\n---\n\n## Why?\n\nAWS CDK already provides mechanisms for creating deployable assets using Docker, such as [DockerImageAsset](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecr_assets.DockerImageAsset.html) and [DockerImageCode](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.DockerImageCode.html), but these constructs are limited because they cannot accept CDK tokens as build-args. The `TokenInjectableDockerBuilder` allows injecting CDK tokens as build-time arguments into Docker-based assets, enabling more dynamic dependency relationships.\n\nFor example, a Next.js frontend Docker image may require an API Gateway URL as an argument to create a reference from the UI to the associated API in a given deployment. With this construct, you can deploy the API Gateway first, then pass its URL as a build-time argument to the Next.js Docker image. As a result, your Next.js frontend can dynamically fetch data from the API Gateway without hardcoding the URL or needing multiple separate stacks.\n\n---\n\n## Features\n\n- **Build and Push Docker Images**: Automatically builds and pushes Docker images to ECR.\n- **Token Support**: Supports custom build arguments for Docker builds, including CDK tokens resolved at deployment time.\n- **Shared Provider (Singleton)**: When building multiple Docker images in the same stack, use `TokenInjectableDockerBuilderProvider` to share a single pair of Lambda functions across all builders, reducing resource overhead from ~2 Lambdas per image to 2 Lambdas total.\n- **Custom Install and Pre-Build Commands**: Allows specifying custom commands to run during the `install` and `pre_build` phases of the CodeBuild build process.\n- **VPC Configuration**: Supports deploying the CodeBuild project within a VPC, with customizable security groups and subnet selection.\n- **Docker Login**: Supports Docker login using credentials stored in AWS Secrets Manager.\n- **ECR Repository Management**: Creates an ECR repository with lifecycle rules (keeps only 3 images by default, configurable via `maxImageCount`) and encryption.\n- **Integration with ECS and Lambda**: Provides outputs for use in AWS ECS and AWS Lambda.\n- **Custom Build Query Interval**: Configure how frequently the custom resource polls for build completion using the `completenessQueryInterval` property (defaults to 30 seconds).\n- **Custom Dockerfile**: Specify a custom Dockerfile name via the `file` property (e.g. `Dockerfile.production`), allowing multiple Docker images from the same source directory.\n- **ECR Docker Layer Caching**: By default, builds use `docker buildx` with ECR as a remote cache backend, reducing build times by reusing layers across deploys. Set `cacheDisabled: true` to force a clean build from scratch.\n- **Platform Support**: Build images for `linux/amd64` (x86_64) or `linux/arm64` (Graviton) using native CodeBuild instances — no emulation, no QEMU. ARM builds are faster and cheaper.\n- **Persistent Build Logs**: Pass `buildLogGroup` with a log group that has RETAIN removal policy so build logs survive rollbacks and stack deletion for debugging.\n- **ECR Pull-Through Cache**: When your Dockerfile uses base images from ECR pull-through cache (e.g. `docker-hub/library/node:20-slim`, `ghcr/org/image:tag`), pass `ecrPullThroughCachePrefixes` to grant the CodeBuild role pull access to those cache prefixes.\n\n---\n\n## Installation\n\n### For NPM\n\nInstall the construct using NPM:\n\n```bash\nnpm install token-injectable-docker-builder\n```\n\n### For Python\n\nInstall the construct using pip:\n\n```bash\npip install token-injectable-docker-builder\n```\n\n---\n\n## API Reference\n\n### `TokenInjectableDockerBuilderProvider`\n\nA singleton construct that creates the `onEvent` and `isComplete` Lambda functions once per stack. When building multiple Docker images, share a single provider to avoid creating redundant Lambda functions.\n\n#### Static Methods\n\n| Method | Description |\n|---|---|\n| `getOrCreate(scope, props?)` | Returns the existing provider for the stack, or creates one if it doesn't exist. |\n\n#### Properties in `TokenInjectableDockerBuilderProviderProps`\n\n| Property | Type | Required | Description |\n|---|---|---|---|\n| `queryInterval` | `Duration` | No | How often the provider polls for build completion. Defaults to `Duration.seconds(30)`. |\n\n#### Instance Properties\n\n| Property | Type | Description |\n|---|---|---|\n| `serviceToken` | `string` | The service token used by CustomResource instances. |\n\n#### Instance Methods\n\n| Method | Description |\n|---|---|\n| `registerProject(project, ecrRepo, encryptionKey?)` | Grants the shared Lambdas permission to start builds and access ECR for a specific CodeBuild project. Called automatically when `provider` is passed to `TokenInjectableDockerBuilder`. |\n\n---\n\n### `TokenInjectableDockerBuilder`\n\n#### Parameters\n\n- **`scope`**: The construct's parent scope.\n- **`id`**: The construct ID.\n- **`props`**: Configuration properties.\n\n#### Properties in `TokenInjectableDockerBuilderProps`\n\n| Property                   | Type                        | Required | Description                                                                                                                                                                                                                                                                                     |\n|----------------------------|-----------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `path`                     | `string`                    | Yes      | The file path to the Dockerfile or source code directory.                                                                                                                                                                                                                                       |\n| `buildArgs`                | `{ [key: string]: string }` | No       | Build arguments to pass to the Docker build process. These are transformed into `--build-arg` flags. To use in Dockerfile, leverage the `ARG` keyword. For more details, please see the [official Docker docs](https://docs.docker.com/build/building/variables/).                             |\n| `provider`                 | `TokenInjectableDockerBuilderProvider` | No | Shared provider for the custom resource Lambdas. Use `TokenInjectableDockerBuilderProvider.getOrCreate(this)` to share a single pair of Lambdas across all builders in the same stack. When omitted, each builder creates its own Lambdas (original behavior). |\n| `dockerLoginSecretArn`     | `string`                    | No       | ARN of an AWS Secrets Manager secret for Docker credentials. Skips login if not provided.                                                                                                                                                                                                        |\n| `vpc`                      | `IVpc`                      | No       | The VPC in which the CodeBuild project will be deployed. If provided, the CodeBuild project will be launched within the specified VPC.                                                                                                                                                           |\n| `securityGroups`           | `ISecurityGroup[]`          | No       | The security groups to attach to the CodeBuild project. These should define the network access rules for the CodeBuild project.                                                                                                                                                                  |\n| `subnetSelection`          | `SubnetSelection`           | No       | The subnet selection to specify which subnets to use within the VPC. Allows the user to select private, public, or isolated subnets.                                                                                                                                                             |\n| `installCommands`          | `string[]`                  | No       | Custom commands to run during the `install` phase of the CodeBuild build process. Will be executed before the Docker image is built. Useful for installing necessary dependencies for running pre-build scripts.                                                                                 |\n| `preBuildCommands`         | `string[]`                  | No       | Custom commands to run during the `pre_build` phase of the CodeBuild build process. Will be executed before the Docker image is built. Useful for running pre-build scripts, such as fetching configs.                                                                                           |\n| `kmsEncryption`            | `boolean`                   | No       | Whether to enable KMS encryption for the ECR repository. If `true`, a KMS key will be created for encrypting ECR images; otherwise, AES-256 encryption is used. Defaults to `false`.                                                                                                          |\n| `completenessQueryInterval`| `Duration`                  | No       | The query interval for checking if the CodeBuild project has completed. This determines how frequently the custom resource polls for build completion. Defaults to `Duration.seconds(30)`. Ignored when `provider` is set (the provider's `queryInterval` is used instead).                   |\n| `exclude`                  | `string[]`                  | No       | A list of file paths in the Docker directory to exclude from the S3 asset bundle. If a `.dockerignore` file is present in the source directory, its contents will be used if this prop is not set. Defaults to an empty list or `.dockerignore` contents.                                    |\n| `file`                     | `string`                    | No       | The name of the Dockerfile to use for the build. Passed as `--file` to `docker build`. Useful when a project has multiple Dockerfiles (e.g. `Dockerfile.production`, `Dockerfile.admin`). Defaults to `Dockerfile`.                                                                        |\n| `cacheDisabled`           | `boolean`                   | No       | When `true`, disables Docker layer caching. Every build runs from scratch. Use for debugging, corrupted cache, or major dependency changes. Defaults to `false`.                                                                                                                          |\n| `platform`                 | `'linux/amd64' \\| 'linux/arm64'` | No  | Target platform for the Docker image. When set to `'linux/arm64'`, uses a native ARM/Graviton CodeBuild instance for fast builds without emulation. Defaults to `'linux/amd64'`.                                                                                                      |\n| `buildLogGroup`            | `ILogGroup`                 | No       | CloudWatch log group for CodeBuild build logs. When provided with RETAIN removal policy, logs survive rollbacks and stack deletion. If not provided, CodeBuild uses default logging (logs are deleted on rollback).                                                                          |\n| `maxImageCount`              | `number`                  | No       | Maximum number of images to retain in the ECR repository. A lifecycle rule automatically expires older images beyond this count. Defaults to `3`. |\n| `ecrPullThroughCachePrefixes` | `string[]`               | No       | ECR pull-through cache repository prefixes to grant pull access to. Use when your Dockerfile references base images from ECR pull-through cache (e.g. `docker-hub/library/node:20-slim`, `ghcr/org/image:tag`). The CodeBuild role is granted `ecr:BatchGetImage`, `ecr:GetDownloadUrlForLayer`, and `ecr:BatchCheckLayerAvailability` on repositories matching each prefix. Example: `['docker-hub', 'ghcr']`. Defaults to no pull-through cache access. |\n\n#### Instance Properties\n\n| Property | Type | Description |\n|---|---|---|\n| `containerImage` | `ContainerImage` | An ECS-compatible container image referencing the built Docker image. |\n| `dockerImageCode` | `DockerImageCode` | A Lambda-compatible Docker image code referencing the built Docker image. |\n\n---\n\n## Usage Examples\n\n### Shared Provider (Recommended for Multiple Images)\n\nWhen building multiple Docker images in the same stack, use a shared provider to avoid creating redundant Lambda functions. Without a shared provider, each builder creates 2 Lambdas + 1 Provider framework Lambda. With 10 images, that's 30 Lambdas. A shared provider reduces this to just 3 Lambdas total.\n\n#### TypeScript/NPM Example\n\n```typescript\nimport * as cdk from 'aws-cdk-lib';\nimport {\n  TokenInjectableDockerBuilder,\n  TokenInjectableDockerBuilderProvider,\n} from 'token-injectable-docker-builder';\nimport * as ecs from 'aws-cdk-lib/aws-ecs';\n\nexport class MultiImageStack extends cdk.Stack {\n  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {\n    super(scope, id, props);\n\n    // Create a shared provider once per stack (singleton)\n    const provider = TokenInjectableDockerBuilderProvider.getOrCreate(this);\n\n    // Build multiple Docker images sharing the same provider\n    const apiBuilder = new TokenInjectableDockerBuilder(this, 'ApiImage', {\n      path: './src/api',\n      provider,\n    });\n\n    const workerBuilder = new TokenInjectableDockerBuilder(this, 'WorkerImage', {\n      path: './src/worker',\n      provider,\n    });\n\n    const frontendBuilder = new TokenInjectableDockerBuilder(this, 'FrontendImage', {\n      path: './src/frontend',\n      buildArgs: { API_URL: 'https://api.example.com' },\n      platform: 'linux/arm64', // Build natively on Graviton\n      provider,\n    });\n\n    // Use in ECS task definitions\n    const taskDef = new ecs.FargateTaskDefinition(this, 'TaskDef');\n    taskDef.addContainer('api', { image: apiBuilder.containerImage });\n    taskDef.addContainer('worker', { image: workerBuilder.containerImage });\n  }\n}\n```\n\n#### Python Example\n\n```python\nfrom aws_cdk import aws_ecs as ecs, core as cdk\nfrom token_injectable_docker_builder import (\n    TokenInjectableDockerBuilder,\n    TokenInjectableDockerBuilderProvider,\n)\n\nclass MultiImageStack(cdk.Stack):\n    def __init__(self, scope: cdk.App, id: str, **kwargs):\n        super().__init__(scope, id, **kwargs)\n\n        # Create a shared provider once per stack (singleton)\n        provider = TokenInjectableDockerBuilderProvider.get_or_create(self)\n\n        # Build multiple Docker images sharing the same provider\n        api_builder = TokenInjectableDockerBuilder(self, \"ApiImage\",\n            path=\"./src/api\",\n            provider=provider,\n        )\n\n        worker_builder = TokenInjectableDockerBuilder(self, \"WorkerImage\",\n            path=\"./src/worker\",\n            provider=provider,\n        )\n\n        frontend_builder = TokenInjectableDockerBuilder(self, \"FrontendImage\",\n            path=\"./src/frontend\",\n            build_args={\"API_URL\": \"https://api.example.com\"},\n            provider=provider,\n        )\n```\n\n### Simple Usage Example\n\nThis example demonstrates the basic usage of the `TokenInjectableDockerBuilder`, where a Next.js frontend Docker image requires an API Gateway URL as a build argument to create a reference from the UI to the associated API in a given deployment.\n\n#### TypeScript/NPM Example\n\n```typescript\nimport * as cdk from 'aws-cdk-lib';\nimport { TokenInjectableDockerBuilder } from 'token-injectable-docker-builder';\nimport * as ecs from 'aws-cdk-lib/aws-ecs';\nimport * as ec2 from 'aws-cdk-lib/aws-ec2';\nimport * as apigateway from 'aws-cdk-lib/aws-apigateway';\n\nexport class SimpleStack extends cdk.Stack {\n  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {\n    super(scope, id, props);\n\n    // Create your API Gateway\n    const api = new apigateway.RestApi(this, 'MyApiGateway', {\n      restApiName: 'MyService',\n    });\n\n    // Create the Docker builder\n    const dockerBuilder = new TokenInjectableDockerBuilder(this, 'SimpleDockerBuilder', {\n      path: './nextjs-app', // Path to your Next.js app Docker context\n      buildArgs: {\n        API_URL: api.url, // Pass the API Gateway URL as a build argument\n      },\n      // Optionally override the default completeness query interval:\n      // completenessQueryInterval: cdk.Duration.seconds(45),\n    });\n\n    // Use in ECS\n    const cluster = new ecs.Cluster(this, 'EcsCluster', {\n      vpc: new ec2.Vpc(this, 'Vpc'),\n    });\n\n    const service = new ecs.FargateService(this, 'FargateService', {\n      cluster,\n      taskDefinition: new ecs.FargateTaskDefinition(this, 'TaskDef', {\n        cpu: 512,\n        memoryLimitMiB: 1024,\n      }).addContainer('Container', {\n        image: dockerBuilder.containerImage,\n        logging: ecs.LogDriver.awsLogs({ streamPrefix: 'MyApp' }),\n      }),\n    });\n\n    service.node.addDependency(dockerBuilder);\n  }\n}\n```\n\n#### Python Example\n\n```python\nfrom aws_cdk import (\n    aws_ecs as ecs,\n    aws_ec2 as ec2,\n    aws_apigateway as apigateway,\n    Duration,\n    core as cdk,\n)\nfrom token_injectable_docker_builder import TokenInjectableDockerBuilder\n\nclass SimpleStack(cdk.Stack):\n\n    def __init__(self, scope: cdk.App, id: str, **kwargs):\n        super().__init__(scope, id, **kwargs)\n\n        # Create your API Gateway\n        api = apigateway.RestApi(self, \"MyApiGateway\",\n            rest_api_name=\"MyService\",\n        )\n\n        # Create the Docker builder\n        docker_builder = TokenInjectableDockerBuilder(self, \"SimpleDockerBuilder\",\n            path=\"./nextjs-app\",  # Path to your Next.js app Docker context\n            build_args={\n                \"API_URL\": api.url,  # Pass the API Gateway URL as a build argument\n            },\n            # Optionally override the default completeness query interval:\n            # completeness_query_interval=Duration.seconds(45)\n        )\n\n        # Use in ECS\n        vpc = ec2.Vpc(self, \"Vpc\")\n        cluster = ecs.Cluster(self, \"EcsCluster\", vpc=vpc)\n\n        task_definition = ecs.FargateTaskDefinition(self, \"TaskDef\",\n            cpu=512,\n            memory_limit_mib=1024,\n        )\n\n        task_definition.node.add_dependency(docker_builder)\n\n        task_definition.add_container(\"Container\",\n            image=docker_builder.container_image,\n            logging=ecs.LogDriver.aws_logs(stream_prefix=\"MyApp\"),\n        )\n\n        ecs.FargateService(self, \"FargateService\",\n            cluster=cluster,\n            task_definition=task_definition,\n        )\n```\n\n---\n\n### Advanced Usage Example\n\nBuilding on the previous example, this advanced usage demonstrates how to include additional configurations, such as fetching private API endpoints and configuration files during the build process.\n\n#### TypeScript/NPM Example\n\n```typescript\nimport * as cdk from 'aws-cdk-lib';\nimport { TokenInjectableDockerBuilder } from 'token-injectable-docker-builder';\nimport * as ecs from 'aws-cdk-lib/aws-ecs';\nimport * as ec2 from 'aws-cdk-lib/aws-ec2';\nimport * as apigateway from 'aws-cdk-lib/aws-apigateway';\n\nexport class AdvancedStack extends cdk.Stack {\n  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {\n    super(scope, id, props);\n\n    // Create your API Gateway\n    const api = new apigateway.RestApi(this, 'MyApiGateway', {\n      restApiName: 'MyService',\n    });\n\n    // VPC and Security Group for CodeBuild\n    const vpc = new ec2.Vpc(this, 'MyVpc');\n    const securityGroup = new ec2.SecurityGroup(this, 'MySecurityGroup', {\n      vpc,\n    });\n\n    // Create the Docker builder with additional pre-build commands\n    const dockerBuilder = new TokenInjectableDockerBuilder(this, 'AdvancedDockerBuilder', {\n      path: './nextjs-app',\n      buildArgs: {\n        API_URL: api.url,\n      },\n      vpc,\n      securityGroups: [securityGroup],\n      subnetSelection: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS },\n      installCommands: [\n        'echo \"Updating package lists...\"',\n        'apt-get update -y',\n        'echo \"Installing necessary packages...\"',\n        'apt-get install -y curl',\n      ],\n      preBuildCommands: [\n        'echo \"Fetching private API configuration...\"',\n        // Replace with your actual command to fetch configs\n        'curl -o config.json https://internal-api.example.com/config',\n      ],\n      // Optionally override the default completeness query interval:\n      // completenessQueryInterval: cdk.Duration.seconds(45),\n    });\n\n    // Use in ECS\n    const cluster = new ecs.Cluster(this, 'EcsCluster', { vpc });\n\n    const service = new ecs.FargateService(this, 'FargateService', {\n      cluster,\n      taskDefinition: new ecs.FargateTaskDefinition(this, 'TaskDef', {\n        cpu: 512,\n        memoryLimitMiB: 1024,\n      }).addContainer('Container', {\n        image: dockerBuilder.containerImage,\n        logging: ecs.LogDriver.awsLogs({ streamPrefix: 'MyApp' }),\n      }),\n    });\n\n    service.node.addDependency(dockerBuilder);\n  }\n}\n```\n\n#### Python Example\n\n```python\nfrom aws_cdk import (\n    aws_ecs as ecs,\n    aws_ec2 as ec2,\n    aws_apigateway as apigateway,\n    Duration,\n    core as cdk,\n)\nfrom token_injectable_docker_builder import TokenInjectableDockerBuilder\n\nclass AdvancedStack(cdk.Stack):\n\n    def __init__(self, scope: cdk.App, id: str, **kwargs):\n        super().__init__(scope, id, **kwargs)\n\n        # Create your API Gateway\n        api = apigateway.RestApi(self, \"MyApiGateway\",\n            rest_api_name=\"MyService\",\n        )\n\n        # VPC and Security Group for CodeBuild\n        vpc = ec2.Vpc(self, \"MyVpc\")\n        security_group = ec2.SecurityGroup(self, \"MySecurityGroup\", vpc=vpc)\n\n        # Create the Docker builder with additional pre-build commands\n        docker_builder = TokenInjectableDockerBuilder(self, \"AdvancedDockerBuilder\",\n            path=\"./nextjs-app\",\n            build_args={\n                \"API_URL\": api.url,\n            },\n            vpc=vpc,\n            security_groups=[security_group],\n            subnet_selection=ec2.SubnetSelection(subnet_type=ec2.SubnetType.PRIVATE_WITH_EGRESS),\n            install_commands=[\n                'echo \"Updating package lists...\"',\n                'apt-get update -y',\n                'echo \"Installing necessary packages...\"',\n                'apt-get install -y curl',\n            ],\n            pre_build_commands=[\n                'echo \"Fetching private API configuration...\"',\n                # Replace with your actual command to fetch configs\n                'curl -o config.json https://internal-api.example.com/config',\n            ],\n            # Optionally override the default completeness query interval:\n            # completeness_query_interval=Duration.seconds(45)\n        )\n\n        # Use in ECS\n        cluster = ecs.Cluster(self, \"EcsCluster\", vpc=vpc)\n\n        task_definition = ecs.FargateTaskDefinition(self, \"TaskDef\",\n            cpu=512,\n            memory_limit_mib=1024,\n        )\n\n        task_definition.node.add_dependency(docker_builder)\n\n        task_definition.add_container(\"Container\",\n            image=docker_builder.container_image,\n            logging=ecs.LogDriver.aws_logs(stream_prefix=\"MyApp\"),\n        )\n\n        ecs.FargateService(self, \"FargateService\",\n            cluster=cluster,\n            task_definition=task_definition,\n        )\n```\n\n### ECR Pull-Through Cache Example\n\nWhen your Dockerfile uses base images from an ECR pull-through cache (e.g. to avoid Docker Hub rate limits), pass `ecrPullThroughCachePrefixes` so the CodeBuild role can pull those images:\n\n```typescript\nimport * as cdk from 'aws-cdk-lib';\nimport {\n  TokenInjectableDockerBuilder,\n  TokenInjectableDockerBuilderProvider,\n} from 'token-injectable-docker-builder';\nimport * as lambda from 'aws-cdk-lib/aws-lambda';\n\nexport class PullThroughCacheStack extends cdk.Stack {\n  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {\n    super(scope, id, props);\n\n    const provider = TokenInjectableDockerBuilderProvider.getOrCreate(this);\n    const node20Slim = `${this.account}.dkr.ecr.${this.region}.amazonaws.com/docker-hub/library/node:20-slim`;\n\n    const apiImage = new TokenInjectableDockerBuilder(this, 'ApiImage', {\n      path: './src',\n      file: 'api/Dockerfile',\n      platform: 'linux/arm64',\n      provider,\n      buildArgs: { NODE_20_SLIM: node20Slim },\n      ecrPullThroughCachePrefixes: ['docker-hub', 'ghcr'],\n    });\n\n    new lambda.DockerImageFunction(this, 'ApiLambda', {\n      code: apiImage.dockerImageCode,\n      architecture: lambda.Architecture.ARM_64,\n    });\n  }\n}\n```\n\n---\n\nIn this advanced example:\n\n- **VPC Configuration**: The CodeBuild project is configured to run inside a VPC with specified security groups and subnet selection, allowing it to access internal resources such as a private API endpoint.\n- **Custom Install and Pre-Build Commands**: The `installCommands` and `preBuildCommands` properties are used to install necessary packages and fetch configuration files from a private API before building the Docker image.\n- **Access to Internal APIs**: By running inside a VPC and configuring the security groups appropriately, the CodeBuild project can access private endpoints not accessible over the public internet.\n\n---\n\n## How It Works\n\n1. **Docker Source**: Packages the source code or Dockerfile specified in the `path` property as an S3 asset.\n2. **CodeBuild Project**:\n   - Uses the packaged asset and `buildArgs` to build the Docker image.\n   - Executes any custom `installCommands` and `preBuildCommands` during the build process.\n   - Pushes the image to an ECR repository.\n   - By default, uses `docker buildx` with ECR registry cache to speed up builds.\n3. **Custom Resource**:\n   - Triggers the build process using a Lambda function (`onEvent`).\n   - Monitors the build status using another Lambda function (`isComplete`) which polls at the interval specified by `completenessQueryInterval` (defaulting to 30 seconds if not provided).\n   - When using a shared `provider`, the same pair of Lambdas handles all builders in the stack.\n4. **Outputs**:\n   - `.containerImage`: Returns the Docker image for ECS.\n   - `.dockerImageCode`: Returns the Docker image code for Lambda.\n\n### Resource Comparison\n\n| Scenario | Lambdas Created | CodeBuild Projects | ECR Repos |\n|---|---|---|---|\n| 5 images, no shared provider | 15 (3 per image) | 5 | 5 |\n| 5 images, shared provider | 3 (shared) | 5 | 5 |\n| 10 images, no shared provider | 30 (3 per image) | 10 | 10 |\n| 10 images, shared provider | 3 (shared) | 10 | 10 |\n\n---\n\n## IAM Permissions\n\nThe construct automatically grants permissions for:\n\n- **CodeBuild**:\n  - Pull and push images to ECR.\n  - Pull from ECR pull-through cache prefixes when `ecrPullThroughCachePrefixes` is provided (e.g. `['docker-hub', 'ghcr']`).\n  - Access to AWS Secrets Manager if `dockerLoginSecretArn` is provided.\n  - Access to the KMS key for encryption.\n- **Lambda Functions** (per-instance or shared provider):\n  - Start and monitor CodeBuild builds.\n  - Access CloudWatch Logs.\n  - Access to the KMS key for encryption.\n  - Pull and push images to ECR.\n\nWhen using the shared provider, `registerProject()` incrementally adds IAM permissions for each CodeBuild project and ECR repository.\n\n---\n\n## Notes\n\n- **Shared Provider**: Use `TokenInjectableDockerBuilderProvider.getOrCreate(this)` when building multiple images in the same stack. This is the recommended approach for stacks with 2+ Docker images.\n- **Build Arguments**: Pass custom arguments via `buildArgs` as `--build-arg` flags. CDK tokens can be used to inject dynamic values resolved at deployment time.\n- **Custom Commands**: Use `installCommands` and `preBuildCommands` to run custom shell commands during the build process. This can be useful for installing dependencies or fetching configuration files.\n- **VPC Configuration**: If your build process requires access to resources within a VPC, you can specify the VPC, security groups, and subnet selection.\n- **Docker Login**: If you need to log in to a private Docker registry before building the image, provide the ARN of a secret in AWS Secrets Manager containing the Docker credentials.\n- **ECR Repository**: Automatically creates an ECR repository with lifecycle rules to manage image retention (keeps 3 images by default, configurable via `maxImageCount`), encryption with a KMS key, and image scanning on push.\n- **Build Query Interval**: The polling frequency for checking build completion can be customized via the `completenessQueryInterval` property (per-instance) or `queryInterval` (shared provider).\n- **Custom Dockerfile**: Use the `file` property to specify a Dockerfile other than the default `Dockerfile`. This is passed as the `--file` flag to `docker build`.\n- **Docker Layer Caching**: By default, builds use ECR as a remote cache backend (via `docker buildx`), which can reduce build times by up to 25%. Set `cacheDisabled: true` when you need a clean build—for example, when debugging, the cache is corrupted, or after major dependency upgrades.\n- **Platform / Architecture**: Set `platform: 'linux/arm64'` to build ARM64/Graviton images using a native ARM CodeBuild instance. Defaults to `'linux/amd64'` (x86_64). Native builds are faster and cheaper than cross-compilation with QEMU.\n- **Build Log Retention**: Pass `buildLogGroup` with a log group that has RETAIN removal policy to ensure build logs survive CloudFormation rollbacks and stack deletion.\n- **ECR Pull-Through Cache**: When using ECR pull-through cache for base images (e.g. to avoid Docker Hub rate limits), pass `ecrPullThroughCachePrefixes: ['docker-hub', 'ghcr']` so the CodeBuild role can pull from those cached repositories. Your ECR registry must have a pull-through cache rule and registry policy configured separately.\n- **Backward Compatibility**: The `provider` prop is optional. Omitting it preserves the original behavior where each builder creates its own Lambdas. Existing code works without changes.\n\n---\n\n## Troubleshooting\n\n1. **Build Errors**: Check the CodeBuild logs in CloudWatch Logs for detailed error messages. If you pass `buildLogGroup` with RETAIN removal policy, logs persist even after rollbacks. Otherwise, logs are deleted when the CodeBuild project is removed during rollback.\n2. **Lambda Errors**: Check the `onEvent` and `isComplete` Lambda function logs in CloudWatch Logs. With a shared provider, both builders' events flow through the same Lambdas—filter by `ProjectName` in the logs.\n3. **\"Image manifest, config or layer media type not supported\" (Lambda)**: Docker Buildx v0.10+ adds provenance attestations by default, producing OCI image indexes that Lambda rejects. This construct disables them with `--provenance=false --sbom=false` so images are Lambda-compatible. If you see this error, ensure you're using a recent version of the construct.\n4. **Permissions**: Ensure IAM roles have the required permissions for CodeBuild, ECR, Secrets Manager, and KMS if applicable. When using a shared provider, verify that `registerProject()` was called for each builder (this happens automatically when passing the `provider` prop).\n5. **Network Access**: If the build requires network access (e.g., to download dependencies or access internal APIs), ensure that the VPC configuration allows necessary network connectivity, and adjust security group rules accordingly.\n\n---\n\n## Support\n\nFor issues or feature requests, please open an issue on [GitHub](https://github.com/AlexTech314/TokenInjectableDockerBuilder).\n\n---\n\n## Reference Links\n\n[![View on Construct Hub](https://constructs.dev/badge?package=token-injectable-docker-builder)](https://constructs.dev/packages/token-injectable-docker-builder)\n\n---\n\n## License\n\nThis project is licensed under the terms of the MIT license.\n\n---\n\n## Acknowledgements\n\n- Inspired by the need for more dynamic Docker asset management in AWS CDK.\n- Thanks to the AWS CDK community for their continuous support and contributions.\n\n---\n\nFeel free to reach out if you have any questions or need further assistance!\n"
+    "markdown": "# TokenInjectableDockerBuilder\n\nThe `TokenInjectableDockerBuilder` is a flexible AWS CDK construct that enables the usage of AWS CDK tokens in the building, pushing, and deployment of Docker images to Amazon Elastic Container Registry (ECR). It leverages AWS CodeBuild and Lambda custom resources.\n\n---\n\n## Why?\n\nAWS CDK already provides mechanisms for creating deployable assets using Docker, such as [DockerImageAsset](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecr_assets.DockerImageAsset.html) and [DockerImageCode](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.DockerImageCode.html), but these constructs are limited because they cannot accept CDK tokens as build-args. The `TokenInjectableDockerBuilder` allows injecting CDK tokens as build-time arguments into Docker-based assets, enabling more dynamic dependency relationships.\n\nFor example, a Next.js frontend Docker image may require an API Gateway URL as an argument to create a reference from the UI to the associated API in a given deployment. With this construct, you can deploy the API Gateway first, then pass its URL as a build-time argument to the Next.js Docker image. As a result, your Next.js frontend can dynamically fetch data from the API Gateway without hardcoding the URL or needing multiple separate stacks.\n\n---\n\n## Features\n\n- **Build and Push Docker Images**: Automatically builds and pushes Docker images to ECR.\n- **Token Support**: Supports custom build arguments for Docker builds, including CDK tokens resolved at deployment time.\n- **Per-stack Lambda singleton**: Every builder in a stack automatically shares one pair of `onEvent` / `isComplete` Lambdas via `TokenInjectableDockerBuilderProvider`. Two builders cost the same Lambda overhead as one.\n- **Cross-region replication**: Pass `replicaRegions: ['us-west-2', ...]` to replicate the built image to additional regions via ECR's native replication. Use `builder.dockerImageCodeFor(scope, region)` / `builder.containerImageFor(scope, region)` in a consumer stack in another region. The custom resource waits for replicas to land before signalling complete, so downstream stacks deploy safely.\n- **Custom Install and Pre-Build Commands**: Allows specifying custom commands to run during the `install` and `pre_build` phases of the CodeBuild build process.\n- **VPC Configuration**: Supports deploying the CodeBuild project within a VPC, with customizable security groups and subnet selection.\n- **Docker Login**: Supports Docker login using credentials stored in AWS Secrets Manager.\n- **Safe ECR retention by default**: Untagged images expire after 30 days; tagged images are never deleted (Lambda pins by digest, so deleting an in-use tag would break the next config update).\n- **Integration with ECS and Lambda**: Provides outputs for use in AWS ECS and AWS Lambda.\n- **Configurable Build Polling**: Tune how often the provider checks for build completion via `TokenInjectableDockerBuilderProvider.getOrCreate(this, { queryInterval })` (defaults to 30 seconds).\n- **Custom Dockerfile**: Specify a custom Dockerfile name via the `file` property (e.g. `Dockerfile.production`), allowing multiple Docker images from the same source directory.\n- **ECR Docker Layer Caching**: By default, builds use `docker buildx` with ECR as a remote cache backend, reducing build times by reusing layers across deploys. Set `cacheDisabled: true` to force a clean build from scratch.\n- **Platform Support**: Build images for `linux/amd64` (x86_64) or `linux/arm64` (Graviton) using native CodeBuild instances — no emulation, no QEMU. ARM builds are faster and cheaper.\n- **Persistent Build Logs**: Pass `buildLogGroup` with a log group that has RETAIN removal policy so build logs survive rollbacks and stack deletion for debugging.\n- **ECR Pull-Through Cache**: When your Dockerfile uses base images from ECR pull-through cache (e.g. `docker-hub/library/node:20-slim`, `ghcr/org/image:tag`), pass `ecrPullThroughCachePrefixes` to grant the CodeBuild role pull access to those cache prefixes.\n\n---\n\n## Installation\n\n### For NPM\n\nInstall the construct using NPM:\n\n```bash\nnpm install token-injectable-docker-builder\n```\n\n### For Python\n\nInstall the construct using pip:\n\n```bash\npip install token-injectable-docker-builder\n```\n\n---\n\n## API Reference\n\n### `TokenInjectableDockerBuilderProvider`\n\nA singleton construct that creates the `onEvent` and `isComplete` Lambda functions once per stack. Every `TokenInjectableDockerBuilder` in the same stack automatically reuses this singleton, so two builders cost the same Lambda overhead as one. You only need to call this yourself if you want to customize `queryInterval`.\n\n#### Static Methods\n\n| Method | Description |\n|---|---|\n| `getOrCreate(scope, props?)` | Returns the existing provider for the stack, or creates one if it doesn't exist. Called automatically by every `TokenInjectableDockerBuilder`. |\n\n#### Properties in `TokenInjectableDockerBuilderProviderProps`\n\n| Property | Type | Required | Description |\n|---|---|---|---|\n| `queryInterval` | `Duration` | No | How often the provider polls for build completion. Defaults to `Duration.seconds(30)`. To override, call `getOrCreate` explicitly **before** creating any builders. |\n\n#### Instance Properties\n\n| Property | Type | Description |\n|---|---|---|\n| `serviceToken` | `string` | The service token used by CustomResource instances. |\n\n#### Instance Methods\n\n| Method | Description |\n|---|---|\n| `registerProject(project, ecrRepo, encryptionKey?)` | Grants the shared Lambdas permission to start builds and access ECR for a specific CodeBuild project. Called automatically by `TokenInjectableDockerBuilder`'s constructor. |\n\n---\n\n### `TokenInjectableDockerBuilder`\n\n#### Parameters\n\n- **`scope`**: The construct's parent scope.\n- **`id`**: The construct ID.\n- **`props`**: Configuration properties.\n\n#### Properties in `TokenInjectableDockerBuilderProps`\n\n| Property                   | Type                        | Required | Description                                                                                                                                                                                                                                                                                     |\n|----------------------------|-----------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `path`                     | `string`                    | Yes      | The file path to the Dockerfile or source code directory.                                                                                                                                                                                                                                       |\n| `buildArgs`                | `{ [key: string]: string }` | No       | Build arguments to pass to the Docker build process. These are transformed into `--build-arg` flags. To use in Dockerfile, leverage the `ARG` keyword. For more details, please see the [official Docker docs](https://docs.docker.com/build/building/variables/).                             |\n| `provider`                 | `TokenInjectableDockerBuilderProvider` | No | Shared provider for the custom resource Lambdas. Defaults to the per-stack singleton — `TokenInjectableDockerBuilderProvider.getOrCreate(this)`. Only pass this explicitly when you need a non-default `queryInterval`. |\n| `dockerLoginSecretArn`     | `string`                    | No       | ARN of an AWS Secrets Manager secret for Docker credentials. Skips login if not provided.                                                                                                                                                                                                        |\n| `vpc`                      | `IVpc`                      | No       | The VPC in which the CodeBuild project will be deployed. If provided, the CodeBuild project will be launched within the specified VPC.                                                                                                                                                           |\n| `securityGroups`           | `ISecurityGroup[]`          | No       | The security groups to attach to the CodeBuild project. These should define the network access rules for the CodeBuild project.                                                                                                                                                                  |\n| `subnetSelection`          | `SubnetSelection`           | No       | The subnet selection to specify which subnets to use within the VPC. Allows the user to select private, public, or isolated subnets.                                                                                                                                                             |\n| `installCommands`          | `string[]`                  | No       | Custom commands to run during the `install` phase of the CodeBuild build process. Will be executed before the Docker image is built. Useful for installing necessary dependencies for running pre-build scripts.                                                                                 |\n| `preBuildCommands`         | `string[]`                  | No       | Custom commands to run during the `pre_build` phase of the CodeBuild build process. Will be executed before the Docker image is built. Useful for running pre-build scripts, such as fetching configs.                                                                                           |\n| `kmsEncryption`            | `boolean`                   | No       | Whether to enable KMS encryption for the ECR repository. If `true`, a KMS key will be created for encrypting ECR images; otherwise, AES-256 encryption is used. Defaults to `false`.                                                                                                          |\n| `exclude`                  | `string[]`                  | No       | A list of file paths in the Docker directory to exclude from the S3 asset bundle. If a `.dockerignore` file is present in the source directory, its contents will be used if this prop is not set. Defaults to an empty list or `.dockerignore` contents.                                    |\n| `file`                     | `string`                    | No       | The name of the Dockerfile to use for the build. Passed as `--file` to `docker build`. Useful when a project has multiple Dockerfiles (e.g. `Dockerfile.production`, `Dockerfile.admin`). Defaults to `Dockerfile`.                                                                        |\n| `cacheDisabled`           | `boolean`                   | No       | When `true`, disables Docker layer caching. Every build runs from scratch. Use for debugging, corrupted cache, or major dependency changes. Defaults to `false`.                                                                                                                          |\n| `platform`                 | `'linux/amd64' \\| 'linux/arm64'` | No  | Target platform for the Docker image. When set to `'linux/arm64'`, uses a native ARM/Graviton CodeBuild instance for fast builds without emulation. Defaults to `'linux/amd64'`.                                                                                                      |\n| `buildLogGroup`            | `ILogGroup`                 | No       | CloudWatch log group for CodeBuild build logs. When provided with RETAIN removal policy, logs survive rollbacks and stack deletion. If not provided, CodeBuild uses default logging (logs are deleted on rollback).                                                                          |\n| `retainBuildLogs`          | `boolean`                   | No       | When `true`, the construct creates a CloudWatch log group at `/docker-builder/<projectName>` **outside** of CloudFormation and routes CodeBuild output there. Because the log group is managed imperatively, it survives stack rollbacks. 7-day retention applies. Defaults to `false`. |\n| `ecrPullThroughCachePrefixes` | `string[]`               | No       | ECR pull-through cache repository prefixes to grant pull access to. Use when your Dockerfile references base images from ECR pull-through cache (e.g. `docker-hub/library/node:20-slim`, `ghcr/org/image:tag`). The CodeBuild role is granted `ecr:BatchGetImage`, `ecr:GetDownloadUrlForLayer`, and `ecr:BatchCheckLayerAvailability` on repositories matching each prefix. Example: `['docker-hub', 'ghcr']`. Defaults to no pull-through cache access. |\n| `replicaRegions`           | `string[]`                  | No       | Additional regions to replicate the image to via ECR's native registry replication. Enables `dockerImageCodeFor(scope, region)` / `containerImageFor(scope, region)` for consumer stacks in those regions. See [Cross-Region Replication](#cross-region-replication) for details and caveats. Defaults to `[]` (no replication). |\n\n#### Instance Properties\n\n| Property | Type | Description |\n|---|---|---|\n| `containerImage` | `ContainerImage` | An ECS-compatible container image referencing the built Docker image **in the primary region**. |\n| `dockerImageCode` | `DockerImageCode` | A Lambda-compatible Docker image code referencing the built Docker image **in the primary region**. |\n| `repositoryName` | `string` | The ECR repository name (same name across all replica regions). |\n| `imageTag` | `string` | The resolved image tag (CFN token; available at deploy time). |\n\n#### Instance Methods (cross-region)\n\n| Method | Description |\n|---|---|\n| `containerImageFor(scope, region)` | Returns an ECS `ContainerImage` pointing at the same tag in `region`. Requires the region to be the primary or in `replicaRegions`. |\n| `dockerImageCodeFor(scope, region)` | Returns a Lambda `DockerImageCode` pointing at the same tag in `region`. Same constraints as above. |\n| `repositoryUriFor(region)` | Returns the regional ECR URI `<account>.dkr.ecr.<region>.amazonaws.com/<repoName>` as a string token. |\n\n---\n\n## Usage Examples\n\n### Multiple Images in One Stack\n\nBuilders in the same stack automatically share a single pair of `onEvent` / `isComplete` Lambdas — there is no per-builder Lambda overhead. Just instantiate as many builders as you need.\n\n#### TypeScript/NPM Example\n\n```typescript\nimport * as cdk from 'aws-cdk-lib';\nimport { TokenInjectableDockerBuilder } from 'token-injectable-docker-builder';\nimport * as ecs from 'aws-cdk-lib/aws-ecs';\n\nexport class MultiImageStack extends cdk.Stack {\n  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {\n    super(scope, id, props);\n\n    // Each builder reuses the same per-stack provider automatically.\n    const apiBuilder = new TokenInjectableDockerBuilder(this, 'ApiImage', {\n      path: './src/api',\n    });\n\n    const workerBuilder = new TokenInjectableDockerBuilder(this, 'WorkerImage', {\n      path: './src/worker',\n    });\n\n    new TokenInjectableDockerBuilder(this, 'FrontendImage', {\n      path: './src/frontend',\n      buildArgs: { API_URL: 'https://api.example.com' },\n      platform: 'linux/arm64', // Build natively on Graviton\n    });\n\n    // Use in ECS task definitions\n    const taskDef = new ecs.FargateTaskDefinition(this, 'TaskDef');\n    taskDef.addContainer('api', { image: apiBuilder.containerImage });\n    taskDef.addContainer('worker', { image: workerBuilder.containerImage });\n  }\n}\n```\n\n#### Python Example\n\n```python\nfrom aws_cdk import aws_ecs as ecs, core as cdk\nfrom token_injectable_docker_builder import TokenInjectableDockerBuilder\n\nclass MultiImageStack(cdk.Stack):\n    def __init__(self, scope: cdk.App, id: str, **kwargs):\n        super().__init__(scope, id, **kwargs)\n\n        # Each builder reuses the same per-stack provider automatically.\n        api_builder = TokenInjectableDockerBuilder(self, \"ApiImage\",\n            path=\"./src/api\",\n        )\n\n        worker_builder = TokenInjectableDockerBuilder(self, \"WorkerImage\",\n            path=\"./src/worker\",\n        )\n\n        TokenInjectableDockerBuilder(self, \"FrontendImage\",\n            path=\"./src/frontend\",\n            build_args={\"API_URL\": \"https://api.example.com\"},\n        )\n```\n\n#### Overriding `queryInterval`\n\nIf you need to tune how often the provider polls for build completion, create the provider singleton explicitly **before** instantiating any builders:\n\n```typescript\nimport { Duration } from 'aws-cdk-lib';\nimport {\n  TokenInjectableDockerBuilder,\n  TokenInjectableDockerBuilderProvider,\n} from 'token-injectable-docker-builder';\n\nconst provider = TokenInjectableDockerBuilderProvider.getOrCreate(this, {\n  queryInterval: Duration.seconds(15),\n});\n\nnew TokenInjectableDockerBuilder(this, 'ApiImage', {\n  path: './src/api',\n  provider, // optional — the builder would resolve the same singleton anyway\n});\n```\n\n### Simple Usage Example\n\nThis example demonstrates the basic usage of the `TokenInjectableDockerBuilder`, where a Next.js frontend Docker image requires an API Gateway URL as a build argument to create a reference from the UI to the associated API in a given deployment.\n\n#### TypeScript/NPM Example\n\n```typescript\nimport * as cdk from 'aws-cdk-lib';\nimport { TokenInjectableDockerBuilder } from 'token-injectable-docker-builder';\nimport * as ecs from 'aws-cdk-lib/aws-ecs';\nimport * as ec2 from 'aws-cdk-lib/aws-ec2';\nimport * as apigateway from 'aws-cdk-lib/aws-apigateway';\n\nexport class SimpleStack extends cdk.Stack {\n  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {\n    super(scope, id, props);\n\n    // Create your API Gateway\n    const api = new apigateway.RestApi(this, 'MyApiGateway', {\n      restApiName: 'MyService',\n    });\n\n    // Create the Docker builder\n    const dockerBuilder = new TokenInjectableDockerBuilder(this, 'SimpleDockerBuilder', {\n      path: './nextjs-app', // Path to your Next.js app Docker context\n      buildArgs: {\n        API_URL: api.url, // Pass the API Gateway URL as a build argument\n      },\n    });\n\n    // Use in ECS\n    const cluster = new ecs.Cluster(this, 'EcsCluster', {\n      vpc: new ec2.Vpc(this, 'Vpc'),\n    });\n\n    const service = new ecs.FargateService(this, 'FargateService', {\n      cluster,\n      taskDefinition: new ecs.FargateTaskDefinition(this, 'TaskDef', {\n        cpu: 512,\n        memoryLimitMiB: 1024,\n      }).addContainer('Container', {\n        image: dockerBuilder.containerImage,\n        logging: ecs.LogDriver.awsLogs({ streamPrefix: 'MyApp' }),\n      }),\n    });\n\n    service.node.addDependency(dockerBuilder);\n  }\n}\n```\n\n#### Python Example\n\n```python\nfrom aws_cdk import (\n    aws_ecs as ecs,\n    aws_ec2 as ec2,\n    aws_apigateway as apigateway,\n    Duration,\n    core as cdk,\n)\nfrom token_injectable_docker_builder import TokenInjectableDockerBuilder\n\nclass SimpleStack(cdk.Stack):\n\n    def __init__(self, scope: cdk.App, id: str, **kwargs):\n        super().__init__(scope, id, **kwargs)\n\n        # Create your API Gateway\n        api = apigateway.RestApi(self, \"MyApiGateway\",\n            rest_api_name=\"MyService\",\n        )\n\n        # Create the Docker builder\n        docker_builder = TokenInjectableDockerBuilder(self, \"SimpleDockerBuilder\",\n            path=\"./nextjs-app\",  # Path to your Next.js app Docker context\n            build_args={\n                \"API_URL\": api.url,  # Pass the API Gateway URL as a build argument\n            },\n        )\n\n        # Use in ECS\n        vpc = ec2.Vpc(self, \"Vpc\")\n        cluster = ecs.Cluster(self, \"EcsCluster\", vpc=vpc)\n\n        task_definition = ecs.FargateTaskDefinition(self, \"TaskDef\",\n            cpu=512,\n            memory_limit_mib=1024,\n        )\n\n        task_definition.node.add_dependency(docker_builder)\n\n        task_definition.add_container(\"Container\",\n            image=docker_builder.container_image,\n            logging=ecs.LogDriver.aws_logs(stream_prefix=\"MyApp\"),\n        )\n\n        ecs.FargateService(self, \"FargateService\",\n            cluster=cluster,\n            task_definition=task_definition,\n        )\n```\n\n---\n\n### Advanced Usage Example\n\nBuilding on the previous example, this advanced usage demonstrates how to include additional configurations, such as fetching private API endpoints and configuration files during the build process.\n\n#### TypeScript/NPM Example\n\n```typescript\nimport * as cdk from 'aws-cdk-lib';\nimport { TokenInjectableDockerBuilder } from 'token-injectable-docker-builder';\nimport * as ecs from 'aws-cdk-lib/aws-ecs';\nimport * as ec2 from 'aws-cdk-lib/aws-ec2';\nimport * as apigateway from 'aws-cdk-lib/aws-apigateway';\n\nexport class AdvancedStack extends cdk.Stack {\n  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {\n    super(scope, id, props);\n\n    // Create your API Gateway\n    const api = new apigateway.RestApi(this, 'MyApiGateway', {\n      restApiName: 'MyService',\n    });\n\n    // VPC and Security Group for CodeBuild\n    const vpc = new ec2.Vpc(this, 'MyVpc');\n    const securityGroup = new ec2.SecurityGroup(this, 'MySecurityGroup', {\n      vpc,\n    });\n\n    // Create the Docker builder with additional pre-build commands\n    const dockerBuilder = new TokenInjectableDockerBuilder(this, 'AdvancedDockerBuilder', {\n      path: './nextjs-app',\n      buildArgs: {\n        API_URL: api.url,\n      },\n      vpc,\n      securityGroups: [securityGroup],\n      subnetSelection: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS },\n      installCommands: [\n        'echo \"Updating package lists...\"',\n        'apt-get update -y',\n        'echo \"Installing necessary packages...\"',\n        'apt-get install -y curl',\n      ],\n      preBuildCommands: [\n        'echo \"Fetching private API configuration...\"',\n        // Replace with your actual command to fetch configs\n        'curl -o config.json https://internal-api.example.com/config',\n      ],\n    });\n\n    // Use in ECS\n    const cluster = new ecs.Cluster(this, 'EcsCluster', { vpc });\n\n    const service = new ecs.FargateService(this, 'FargateService', {\n      cluster,\n      taskDefinition: new ecs.FargateTaskDefinition(this, 'TaskDef', {\n        cpu: 512,\n        memoryLimitMiB: 1024,\n      }).addContainer('Container', {\n        image: dockerBuilder.containerImage,\n        logging: ecs.LogDriver.awsLogs({ streamPrefix: 'MyApp' }),\n      }),\n    });\n\n    service.node.addDependency(dockerBuilder);\n  }\n}\n```\n\n#### Python Example\n\n```python\nfrom aws_cdk import (\n    aws_ecs as ecs,\n    aws_ec2 as ec2,\n    aws_apigateway as apigateway,\n    Duration,\n    core as cdk,\n)\nfrom token_injectable_docker_builder import TokenInjectableDockerBuilder\n\nclass AdvancedStack(cdk.Stack):\n\n    def __init__(self, scope: cdk.App, id: str, **kwargs):\n        super().__init__(scope, id, **kwargs)\n\n        # Create your API Gateway\n        api = apigateway.RestApi(self, \"MyApiGateway\",\n            rest_api_name=\"MyService\",\n        )\n\n        # VPC and Security Group for CodeBuild\n        vpc = ec2.Vpc(self, \"MyVpc\")\n        security_group = ec2.SecurityGroup(self, \"MySecurityGroup\", vpc=vpc)\n\n        # Create the Docker builder with additional pre-build commands\n        docker_builder = TokenInjectableDockerBuilder(self, \"AdvancedDockerBuilder\",\n            path=\"./nextjs-app\",\n            build_args={\n                \"API_URL\": api.url,\n            },\n            vpc=vpc,\n            security_groups=[security_group],\n            subnet_selection=ec2.SubnetSelection(subnet_type=ec2.SubnetType.PRIVATE_WITH_EGRESS),\n            install_commands=[\n                'echo \"Updating package lists...\"',\n                'apt-get update -y',\n                'echo \"Installing necessary packages...\"',\n                'apt-get install -y curl',\n            ],\n            pre_build_commands=[\n                'echo \"Fetching private API configuration...\"',\n                # Replace with your actual command to fetch configs\n                'curl -o config.json https://internal-api.example.com/config',\n            ],\n        )\n\n        # Use in ECS\n        cluster = ecs.Cluster(self, \"EcsCluster\", vpc=vpc)\n\n        task_definition = ecs.FargateTaskDefinition(self, \"TaskDef\",\n            cpu=512,\n            memory_limit_mib=1024,\n        )\n\n        task_definition.node.add_dependency(docker_builder)\n\n        task_definition.add_container(\"Container\",\n            image=docker_builder.container_image,\n            logging=ecs.LogDriver.aws_logs(stream_prefix=\"MyApp\"),\n        )\n\n        ecs.FargateService(self, \"FargateService\",\n            cluster=cluster,\n            task_definition=task_definition,\n        )\n```\n\n### ECR Pull-Through Cache Example\n\nWhen your Dockerfile uses base images from an ECR pull-through cache (e.g. to avoid Docker Hub rate limits), pass `ecrPullThroughCachePrefixes` so the CodeBuild role can pull those images:\n\n```typescript\nimport * as cdk from 'aws-cdk-lib';\nimport { TokenInjectableDockerBuilder } from 'token-injectable-docker-builder';\nimport * as lambda from 'aws-cdk-lib/aws-lambda';\n\nexport class PullThroughCacheStack extends cdk.Stack {\n  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {\n    super(scope, id, props);\n\n    const node20Slim = `${this.account}.dkr.ecr.${this.region}.amazonaws.com/docker-hub/library/node:20-slim`;\n\n    const apiImage = new TokenInjectableDockerBuilder(this, 'ApiImage', {\n      path: './src',\n      file: 'api/Dockerfile',\n      platform: 'linux/arm64',\n      buildArgs: { NODE_20_SLIM: node20Slim },\n      ecrPullThroughCachePrefixes: ['docker-hub', 'ghcr'],\n    });\n\n    new lambda.DockerImageFunction(this, 'ApiLambda', {\n      code: apiImage.dockerImageCode,\n      architecture: lambda.Architecture.ARM_64,\n    });\n  }\n}\n```\n\n---\n\nIn this advanced example:\n\n- **VPC Configuration**: The CodeBuild project is configured to run inside a VPC with specified security groups and subnet selection, allowing it to access internal resources such as a private API endpoint.\n- **Custom Install and Pre-Build Commands**: The `installCommands` and `preBuildCommands` properties are used to install necessary packages and fetch configuration files from a private API before building the Docker image.\n- **Access to Internal APIs**: By running inside a VPC and configuring the security groups appropriately, the CodeBuild project can access private endpoints not accessible over the public internet.\n\n---\n\n### Cross-Region Replication\n\nSet `replicaRegions` to make the built image available in additional regions, then reference it from a consumer stack in any of those regions.\n\n```typescript\nimport * as cdk from 'aws-cdk-lib';\nimport { TokenInjectableDockerBuilder } from 'token-injectable-docker-builder';\nimport * as lambda from 'aws-cdk-lib/aws-lambda';\n\nconst app = new cdk.App();\n\n// Builder stack — us-east-1\nconst builderStack = new cdk.Stack(app, 'BuilderStack', {\n  env: { account: '123456789012', region: 'us-east-1' },\n  crossRegionReferences: true,\n});\n\nconst apiImage = new TokenInjectableDockerBuilder(builderStack, 'ApiImage', {\n  path: './src/api',\n  replicaRegions: ['us-west-2', 'eu-west-1'],\n});\n\n// Consumer stack — us-west-2\nconst consumerStack = new cdk.Stack(app, 'ConsumerStack', {\n  env: { account: '123456789012', region: 'us-west-2' },\n  crossRegionReferences: true,\n});\n\nnew lambda.DockerImageFunction(consumerStack, 'ApiLambda', {\n  code: apiImage.dockerImageCodeFor(consumerStack, 'us-west-2'),\n});\n```\n\n**How it works**\n\n1. The builder pushes to its primary-region ECR repository as usual.\n2. The provider singleton manages a single registry-replication custom resource that calls `PutReplicationConfiguration` with merged rules (one rule per unique destination set, filtered to each managed repository name).\n3. ECR asynchronously replicates the image to every region in `replicaRegions`. Most images replicate in under 30 minutes; rare cases take longer.\n4. The build's `isComplete` Lambda polls each replica region's ECR via `BatchGetImage` and only returns `IsComplete=true` once every replica has the tag. The Provider's `totalTimeout` is bumped to 1 hour to accommodate replication lag.\n5. The consumer stack's `dockerImageCodeFor` / `containerImageFor` imports the replicated repository by name in the consumer's region and references the tag via CDK's cross-region SSM mechanism.\n\n**Caveats to read before enabling**\n\n- **Stacks must have a concrete `env`**: env-agnostic stacks (where `region` is a token) don't work with `crossRegionReferences`. Pass `env: { account, region }` explicitly on both builder and consumer stacks.\n- **Replicas don't inherit settings**: ECR replication does NOT copy encryption (KMS), lifecycle policies, or repository policies. Replicated repos default to AES-256 encryption with no lifecycle rules. If you need stricter replica configuration, set up [ECR repository creation templates](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-creation-templates.html) separately.\n- **Replicas persist on stack delete**: AWS does NOT auto-delete replicated repositories when the source replication rule is removed. After `cdk destroy`, manually delete leftover repos: `aws ecr delete-repository --region <replica> --repository-name <name> --force`.\n- **Registry-level limits enforced at synth time**: ECR allows 10 rules per registry and 25 unique destinations across all rules per AWS account. The construct enforces both caps **at synth time** — `cdk synth` will throw a clear error if the union of `replicaRegions` across all builders in the stack would exceed either limit, instead of failing at deploy time inside the replication CR. Rule-grouping by destination set keeps you under the 10-rules cap until you have more than 10 *distinct* destination sets (e.g. ten builders each replicating to a different single region). Note that this is a best-effort check: rules created outside this construct (other stacks, manual setup) aren't visible at synth time, so the runtime API can still surface them.\n- **Cross-partition is unsupported**: e.g. `us-east-1` → `cn-north-1` won't work. The construct will throw at synth time when both partition values are concrete and differ.\n- **Replication latency**: deploys can extend by up to ~30 min in rare cases while `isComplete` waits for replicas. The CDK Provider framework caps `totalTimeout` at 2 hours.\n\n---\n\n## How It Works\n\n1. **Docker Source**: Packages the source code or Dockerfile specified in the `path` property as an S3 asset.\n2. **CodeBuild Project**:\n   - Uses the packaged asset and `buildArgs` to build the Docker image.\n   - Executes any custom `installCommands` and `preBuildCommands` during the build process.\n   - Pushes the image to an ECR repository.\n   - By default, uses `docker buildx` with ECR registry cache to speed up builds.\n3. **Custom Resource** (one pair of Lambdas per stack):\n   - Triggers the build using `onEvent`.\n   - Monitors build status using `isComplete`, polling at the interval set on the provider singleton (defaults to 30 seconds; override via `TokenInjectableDockerBuilderProvider.getOrCreate(this, { queryInterval })`).\n   - The same Lambda pair handles every builder in the stack — they are not duplicated per builder.\n4. **Outputs**:\n   - `.containerImage`: Returns the Docker image for ECS.\n   - `.dockerImageCode`: Returns the Docker image code for Lambda.\n\n### Resource Comparison\n\nThe provider singleton means a stack's Lambda overhead is fixed — adding more builders only adds CodeBuild projects and ECR repositories.\n\n| Scenario | Lambdas (total) | CodeBuild Projects | ECR Repos |\n|---|---|---|---|\n| 1 image | 5 (2 user + 3 framework) | 1 | 1 |\n| 5 images | 5 | 5 | 5 |\n| 10 images | 5 | 10 | 10 |\n\nThe 3 framework Lambdas are CDK's [`Provider`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.custom_resources.Provider.html) framework internals (`framework.onEvent`, `framework.isComplete`, `framework.onTimeout`).\n\n---\n\n## IAM Permissions\n\nThe construct automatically grants permissions for:\n\n- **CodeBuild**:\n  - Pull and push images to ECR.\n  - Pull from ECR pull-through cache prefixes when `ecrPullThroughCachePrefixes` is provided (e.g. `['docker-hub', 'ghcr']`).\n  - Access to AWS Secrets Manager if `dockerLoginSecretArn` is provided.\n  - Access to the KMS key for encryption.\n- **Shared Provider Lambdas** (one pair per stack):\n  - Start and monitor CodeBuild builds.\n  - Access CloudWatch Logs.\n  - Access to the KMS key for encryption.\n  - Pull and push images to ECR.\n\nEvery new builder calls `provider.registerProject()` under the hood, incrementally adding `codebuild:StartBuild` for its project ARN and `ecr:PullPush` for its repository.\n\n---\n\n## Notes\n\n- **Provider Singleton**: One pair of `onEvent` / `isComplete` Lambdas is created the first time a builder is instantiated in a stack and reused by every subsequent builder in the same stack. You generally do not need to touch `TokenInjectableDockerBuilderProvider` directly — only call `getOrCreate` yourself if you want to change `queryInterval`.\n- **Build Arguments**: Pass custom arguments via `buildArgs` as `--build-arg` flags. CDK tokens can be used to inject dynamic values resolved at deployment time.\n- **Custom Commands**: Use `installCommands` and `preBuildCommands` to run custom shell commands during the build process. This can be useful for installing dependencies or fetching configuration files.\n- **VPC Configuration**: If your build process requires access to resources within a VPC, you can specify the VPC, security groups, and subnet selection.\n- **Docker Login**: If you need to log in to a private Docker registry before building the image, provide the ARN of a secret in AWS Secrets Manager containing the Docker credentials.\n- **ECR Retention (safe by default)**: Tagged images are kept indefinitely; untagged images are removed after 30 days. There is no count-based expiration — Lambda pins images by digest internally and count-based deletion would silently remove an image that an in-use Lambda is still pinned to, breaking the next config update with `Image ID cannot be found`.\n- **Build Query Interval**: Tune polling frequency with `TokenInjectableDockerBuilderProvider.getOrCreate(this, { queryInterval })`. Call this **before** instantiating any builders, otherwise the builder will create the singleton with the default 30 second interval.\n- **Custom Dockerfile**: Use the `file` property to specify a Dockerfile other than the default `Dockerfile`. This is passed as the `--file` flag to `docker build`.\n- **Docker Layer Caching**: By default, builds use ECR as a remote cache backend (via `docker buildx`), which can reduce build times by up to 25%. Set `cacheDisabled: true` when you need a clean build—for example, when debugging, the cache is corrupted, or after major dependency upgrades.\n- **Platform / Architecture**: Set `platform: 'linux/arm64'` to build ARM64/Graviton images using a native ARM CodeBuild instance. Defaults to `'linux/amd64'` (x86_64). Native builds are faster and cheaper than cross-compilation with QEMU.\n- **Build Log Retention**: Pass `buildLogGroup` with a log group that has RETAIN removal policy, or set `retainBuildLogs: true` to let the construct manage a `/docker-builder/<projectName>` log group imperatively (survives rollbacks; 7-day retention).\n- **ECR Pull-Through Cache**: When using ECR pull-through cache for base images (e.g. to avoid Docker Hub rate limits), pass `ecrPullThroughCachePrefixes: ['docker-hub', 'ghcr']` so the CodeBuild role can pull from those cached repositories. Your ECR registry must have a pull-through cache rule and registry policy configured separately.\n\n### Migrating from v1\n\n**Recipe for the common case** (you're on `^1.x` and want to move to `^2.x`):\n\n```bash\nnpm install token-injectable-docker-builder@^2\n```\n\nThat's the entire required code change for most users. The construct handles the CFN-level migration internally.\n\n**What happens on the first `cdk deploy` after upgrading:**\n\n1. Every `BuildTriggerResource` in your stack is **replaced** by `BuildTriggerResourceV2`. CFN does this because the construct deliberately renames its internal custom resource between v1 and v2 — this is what sidesteps CFN's `Modifying service token is not allowed` rule when the CR's serviceToken changes from v1's per-instance provider to v2's singleton provider. **Without this rename, the upgrade would fail at the CFN level for users who didn't pass `provider` explicitly in v1.**\n2. Each replacement triggers **one fresh CodeBuild run per builder** (5–10 min each in parallel). Image tags transition from v1's random-UUID style to v2's deterministic-hash style.\n3. Downstream `DockerImageFunction` / `FargateTaskDefinition` resources update in place to the new tag. Lambda's blue/green update is transparent; ECS does a normal rolling deploy.\n4. v1's per-instance `OnEventHandlerFunction` / `IsCompleteHandlerFunction` / `CustomResourceProvider` Lambdas (one set per builder) are deleted. The singleton at `<Stack>/TokenInjectableDockerBuilderProvider/...` is the only provider left.\n5. ECR repositories keep their logical IDs and contents — **no images are lost**.\n\n**Behavior changes that come for free (no code edit needed):**\n\n- ECR retention switches from \"keep 3 tagged images\" (v1 default with `maxImageCount: 3`) to \"keep all tagged images, untagged-after-30-days only\". v1's count-based expiration could silently delete an image a Lambda was pinned to.\n- `imageTag` is now a deterministic SHA-256 hash of all build inputs. v1 regenerated a UUID on every synth, causing a build on every deploy; v2 only rebuilds when source / buildArgs / platform / commands actually change.\n\n**Breaking changes that may require a source edit:**\n\n- **`completenessQueryInterval`** was removed from `TokenInjectableDockerBuilderProps`. If you set it, move the value to `TokenInjectableDockerBuilderProvider.getOrCreate(this, { queryInterval })` (call before any builder; it now applies stack-wide). If you didn't set it, no edit needed.\n- **`maxImageCount`** was removed entirely. If you set it, just delete the prop from your builder props (no replacement; the behavior is now non-configurable).\n\n**This migration path is exercised end-to-end by `npm run integ-migration`** — see `test/migration/before-v1.ts` and `test/migration/after-v2.ts` for the executable recipe. The literal source-code diff between the two files is the import path; everything else is identical.\n\n---\n\n## Troubleshooting\n\n1. **Build Errors**: Check the CodeBuild logs in CloudWatch Logs for detailed error messages. If you pass `buildLogGroup` with RETAIN removal policy, or set `retainBuildLogs: true`, logs persist even after rollbacks. Otherwise, logs are deleted when the CodeBuild project is removed during rollback.\n2. **Lambda Errors**: Check the singleton `onEvent` and `isComplete` Lambda function logs in CloudWatch Logs (under `TokenInjectableDockerBuilderProvider/...`). All builders in the stack flow through the same Lambdas — filter by `ProjectName` in the logs to isolate a specific builder.\n3. **\"Image manifest, config or layer media type not supported\" (Lambda)**: Docker Buildx v0.10+ adds provenance attestations by default, producing OCI image indexes that Lambda rejects. This construct disables them with `--provenance=false --sbom=false` so images are Lambda-compatible. If you see this error, ensure you're using a recent version of the construct.\n4. **Permissions**: Ensure IAM roles have the required permissions for CodeBuild, ECR, Secrets Manager, and KMS if applicable. `registerProject()` is called automatically by the builder's constructor — you do not need to call it manually.\n5. **Network Access**: If the build requires network access (e.g., to download dependencies or access internal APIs), ensure that the VPC configuration allows necessary network connectivity, and adjust security group rules accordingly.\n\n---\n\n## Support\n\nFor issues or feature requests, please open an issue on [GitHub](https://github.com/AlexTech314/TokenInjectableDockerBuilder).\n\n---\n\n## Reference Links\n\n[![View on Construct Hub](https://constructs.dev/badge?package=token-injectable-docker-builder)](https://constructs.dev/packages/token-injectable-docker-builder)\n\n---\n\n## License\n\nThis project is licensed under the terms of the MIT license.\n\n---\n\n## Acknowledgements\n\n- Inspired by the need for more dynamic Docker asset management in AWS CDK.\n- Thanks to the AWS CDK community for their continuous support and contributions.\n\n---\n\nFeel free to reach out if you have any questions or need further assistance!\n"
   },
   "repository": {
     "type": "git",
@@ -8558,41 +8558,31 @@
       "base": "constructs.Construct",
       "docs": {
         "stability": "stable",
-        "summary": "A CDK construct to build and push Docker images to an ECR repository using CodeBuild and Lambda custom resources, **then** retrieve the final image tag so that ECS/Lambda references use the exact digest."
+        "summary": "A CDK construct to build and push Docker images to an ECR repository using CodeBuild and Lambda custom resources, **then** retrieve the final image tag so that ECS/Lambda references use the exact built image."
       },
       "fqn": "token-injectable-docker-builder.TokenInjectableDockerBuilder",
       "initializer": {
         "docs": {
-          "stability": "stable",
-          "summary": "Creates a new `TokenInjectableDockerBuilder`."
+          "stability": "stable"
         },
         "locationInModule": {
-          "filename": "src/index.ts",
-          "line": 361
+          "filename": "src/builder.ts",
+          "line": 219
         },
         "parameters": [
           {
-            "docs": {
-              "summary": "The scope in which to define this construct."
-            },
             "name": "scope",
             "type": {
               "fqn": "constructs.Construct"
             }
           },
           {
-            "docs": {
-              "summary": "The scoped construct ID."
-            },
             "name": "id",
             "type": {
               "primitive": "string"
             }
           },
           {
-            "docs": {
-              "summary": "Configuration for building and pushing the Docker image."
-            },
             "name": "props",
             "type": {
               "fqn": "token-injectable-docker-builder.TokenInjectableDockerBuilderProps"
@@ -8602,20 +8592,109 @@
       },
       "kind": "class",
       "locationInModule": {
-        "filename": "src/index.ts",
-        "line": 336
+        "filename": "src/builder.ts",
+        "line": 199
       },
+      "methods": [
+        {
+          "docs": {
+            "remarks": "The consumer's stack must have `crossRegionReferences: true` when\n`region` differs from the builder's region.",
+            "stability": "stable",
+            "summary": "Import the replicated repository as an ECS-compatible `ContainerImage` in a consumer scope (typically a stack in `region`)."
+          },
+          "locationInModule": {
+            "filename": "src/builder.ts",
+            "line": 392
+          },
+          "name": "containerImageFor",
+          "parameters": [
+            {
+              "name": "scope",
+              "type": {
+                "fqn": "constructs.Construct"
+              }
+            },
+            {
+              "name": "region",
+              "type": {
+                "primitive": "string"
+              }
+            }
+          ],
+          "returns": {
+            "type": {
+              "fqn": "aws-cdk-lib.aws_ecs.ContainerImage"
+            }
+          }
+        },
+        {
+          "docs": {
+            "remarks": "The consumer's stack must have `crossRegionReferences: true` when\n`region` differs from the builder's region.",
+            "stability": "stable",
+            "summary": "Import the replicated repository as a Lambda-compatible `DockerImageCode` in a consumer scope (typically a stack in `region`)."
+          },
+          "locationInModule": {
+            "filename": "src/builder.ts",
+            "line": 406
+          },
+          "name": "dockerImageCodeFor",
+          "parameters": [
+            {
+              "name": "scope",
+              "type": {
+                "fqn": "constructs.Construct"
+              }
+            },
+            {
+              "name": "region",
+              "type": {
+                "primitive": "string"
+              }
+            }
+          ],
+          "returns": {
+            "type": {
+              "fqn": "aws-cdk-lib.aws_lambda.DockerImageCode"
+            }
+          }
+        },
+        {
+          "docs": {
+            "remarks": "The region must\nbe either the primary region or one of `replicaRegions`.",
+            "stability": "stable",
+            "summary": "Format the ECR repository URI for a given region."
+          },
+          "locationInModule": {
+            "filename": "src/builder.ts",
+            "line": 380
+          },
+          "name": "repositoryUriFor",
+          "parameters": [
+            {
+              "name": "region",
+              "type": {
+                "primitive": "string"
+              }
+            }
+          ],
+          "returns": {
+            "type": {
+              "primitive": "string"
+            }
+          }
+        }
+      ],
       "name": "TokenInjectableDockerBuilder",
       "properties": [
         {
           "docs": {
             "stability": "stable",
-            "summary": "An ECS-compatible container image referencing the tag of the built Docker image."
+            "summary": "ECS-compatible container image reference (primary region)."
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 346
+            "filename": "src/builder.ts",
+            "line": 204
           },
           "name": "containerImage",
           "type": {
@@ -8625,20 +8704,51 @@
         {
           "docs": {
             "stability": "stable",
-            "summary": "A Lambda-compatible DockerImageCode referencing the tag of the built Docker image."
+            "summary": "Lambda-compatible DockerImageCode reference (primary region)."
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 352
+            "filename": "src/builder.ts",
+            "line": 207
           },
           "name": "dockerImageCode",
           "type": {
             "fqn": "aws-cdk-lib.aws_lambda.DockerImageCode"
           }
+        },
+        {
+          "docs": {
+            "remarks": "available at deploy time).",
+            "stability": "stable",
+            "summary": "The resolved image tag (CFN token;"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/builder.ts",
+            "line": 213
+          },
+          "name": "imageTag",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "docs": {
+            "stability": "stable",
+            "summary": "The ECR repository name — preserved across replica regions."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/builder.ts",
+            "line": 210
+          },
+          "name": "repositoryName",
+          "type": {
+            "primitive": "string"
+          }
         }
       ],
-      "symbolId": "src/index:TokenInjectableDockerBuilder"
+      "symbolId": "src/builder:TokenInjectableDockerBuilder"
     },
     "token-injectable-docker-builder.TokenInjectableDockerBuilderProps": {
       "assembly": "token-injectable-docker-builder",
@@ -8650,8 +8760,8 @@
       "fqn": "token-injectable-docker-builder.TokenInjectableDockerBuilderProps",
       "kind": "interface",
       "locationInModule": {
-        "filename": "src/index.ts",
-        "line": 130
+        "filename": "src/builder.ts",
+        "line": 29
       },
       "name": "TokenInjectableDockerBuilderProps",
       "properties": [
@@ -8663,8 +8773,8 @@
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 134
+            "filename": "src/builder.ts",
+            "line": 33
           },
           "name": "path",
           "type": {
@@ -8681,8 +8791,8 @@
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 145
+            "filename": "src/builder.ts",
+            "line": 44
           },
           "name": "buildArgs",
           "optional": true,
@@ -8698,15 +8808,14 @@
         {
           "abstract": true,
           "docs": {
-            "default": "- CodeBuild default logging (logs are deleted on rollback)",
-            "remarks": "When provided with a RETAIN removal policy, build logs survive rollbacks\nand stack deletion for debugging.",
+            "default": "- CodeBuild default logging.",
             "stability": "stable",
             "summary": "CloudWatch log group for CodeBuild build logs."
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 267
+            "filename": "src/builder.ts",
+            "line": 125
           },
           "name": "buildLogGroup",
           "optional": true,
@@ -8718,14 +8827,13 @@
           "abstract": true,
           "docs": {
             "default": "false",
-            "remarks": "Every build runs from scratch.\nUse for debugging, corrupted cache, or major dependency changes.",
             "stability": "stable",
             "summary": "When `true`, disables Docker layer caching."
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 258
+            "filename": "src/builder.ts",
+            "line": 118
           },
           "name": "cacheDisabled",
           "optional": true,
@@ -8736,34 +8844,15 @@
         {
           "abstract": true,
           "docs": {
-            "default": "- Duration.seconds(30)",
-            "remarks": "This determines how frequently the custom resource polls for build completion.",
-            "stability": "stable",
-            "summary": "The query interval for checking if the CodeBuild project has completed."
-          },
-          "immutable": true,
-          "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 233
-          },
-          "name": "completenessQueryInterval",
-          "optional": true,
-          "type": {
-            "fqn": "aws-cdk-lib.Duration"
-          }
-        },
-        {
-          "abstract": true,
-          "docs": {
-            "example": "'arn:aws:secretsmanager:us-east-1:123456789012:secret:DockerLoginSecret'",
-            "remarks": "This secret should store a JSON object with the following structure:\n```json\n{\n  \"username\": \"my-docker-username\",\n  \"password\": \"my-docker-password\"\n}\n```\nIf not provided (or not needed), the construct will skip Docker Hub login.\n\n**Note**: The secret must be in the same region as the stack.",
+            "default": "- No Docker Hub login.",
+            "remarks": "The secret must store a JSON object: `{\"username\":\"...\",\"password\":\"...\"}`.\nMust be in the same region as the stack.",
             "stability": "stable",
             "summary": "The ARN of the AWS Secrets Manager secret containing Docker login credentials."
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 162
+            "filename": "src/builder.ts",
+            "line": 53
           },
           "name": "dockerLoginSecretArn",
           "optional": true,
@@ -8774,16 +8863,15 @@
         {
           "abstract": true,
           "docs": {
-            "default": "- No pull-through cache access",
+            "default": "- No pull-through cache access.",
             "example": "['docker-hub', 'ghcr']",
-            "remarks": "Use when your Dockerfile references base images from ECR pull-through\ncache (e.g. docker-hub/library/node:20-slim, ghcr/org/image:tag).\nThe CodeBuild role will be granted ecr:BatchGetImage, ecr:GetDownloadUrlForLayer,\nand ecr:BatchCheckLayerAvailability on repositories matching each prefix.",
             "stability": "stable",
             "summary": "ECR pull-through cache repository prefixes to grant pull access to."
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 300
+            "filename": "src/builder.ts",
+            "line": 151
           },
           "name": "ecrPullThroughCachePrefixes",
           "optional": true,
@@ -8799,15 +8887,15 @@
         {
           "abstract": true,
           "docs": {
-            "default": "- No file path exclusions",
-            "remarks": "Will use paths in .dockerignore file if present.",
+            "default": "- No file path exclusions.",
+            "remarks": "Falls back to `.dockerignore` if present.",
             "stability": "stable",
-            "summary": "A list of file paths in the Docker directory to exclude from build."
+            "summary": "File paths in the Docker directory to exclude from the build asset."
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 241
+            "filename": "src/builder.ts",
+            "line": 103
           },
           "name": "exclude",
           "optional": true,
@@ -8825,14 +8913,13 @@
           "docs": {
             "default": "'Dockerfile'",
             "example": "'Dockerfile.production'",
-            "remarks": "Passed as `--file` to `docker build`.",
             "stability": "stable",
-            "summary": "The name of the Dockerfile to use for the build."
+            "summary": "Name of the Dockerfile (passed as `-f`)."
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 250
+            "filename": "src/builder.ts",
+            "line": 111
           },
           "name": "file",
           "optional": true,
@@ -8844,14 +8931,13 @@
           "abstract": true,
           "docs": {
             "default": "- No additional install commands.",
-            "remarks": "**Example**:\n```ts\ninstallCommands: [\n  'echo \"Updating package lists...\"',\n  'apt-get update -y',\n  'echo \"Installing required packages...\"',\n  'apt-get install -y curl dnsutils',\n],\n```",
             "stability": "stable",
             "summary": "Custom commands to run during the install phase of CodeBuild."
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 202
+            "filename": "src/builder.ts",
+            "line": 81
           },
           "name": "installCommands",
           "optional": true,
@@ -8867,15 +8953,14 @@
         {
           "abstract": true,
           "docs": {
-            "default": "- false",
-            "remarks": "If `true`, a KMS key will be created for encrypting ECR images.\nIf `false`, the repository will use AES-256 encryption.",
+            "default": "false",
             "stability": "stable",
             "summary": "Whether to enable KMS encryption for the ECR repository."
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 225
+            "filename": "src/builder.ts",
+            "line": 95
           },
           "name": "kmsEncryption",
           "optional": true,
@@ -8883,37 +8968,17 @@
             "primitive": "boolean"
           }
         },
-        {
-          "abstract": true,
-          "docs": {
-            "default": "undefined - no count-based expiration; only untagged-after-30-days",
-            "remarks": "**WARNING:** Lambda functions pin images by digest internally even when\nreferenced by tag. Setting this can delete images that Lambda functions\n(and ECS tasks) are still pinned to, breaking the next configuration\nupdate with \"Image ID cannot be found\".\n\nLeave undefined (the default) for production use. Untagged images are\nalways cleaned up after 30 days regardless of this setting.",
-            "stability": "stable",
-            "summary": "Maximum number of tagged images to retain in the ECR repository."
-          },
-          "immutable": true,
-          "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 315
-          },
-          "name": "maxImageCount",
-          "optional": true,
-          "type": {
-            "primitive": "number"
-          }
-        },
         {
           "abstract": true,
           "docs": {
             "default": "'linux/amd64'",
-            "remarks": "When set to `'linux/arm64'`, the construct uses a native ARM/Graviton\nCodeBuild instance for fast builds without emulation.",
             "stability": "stable",
             "summary": "Target platform for the Docker image."
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 277
+            "filename": "src/builder.ts",
+            "line": 132
           },
           "name": "platform",
           "optional": true,
@@ -8925,14 +8990,13 @@
           "abstract": true,
           "docs": {
             "default": "- No additional pre-build commands.",
-            "remarks": "**Example**:\n```ts\npreBuildCommands: [\n  'echo \"Fetching configuration from private API...\"',\n  'curl -o config.json https://api.example.com/config',\n],\n```",
             "stability": "stable",
             "summary": "Custom commands to run during the pre_build phase of CodeBuild."
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 216
+            "filename": "src/builder.ts",
+            "line": 88
           },
           "name": "preBuildCommands",
           "optional": true,
@@ -8948,15 +9012,15 @@
         {
           "abstract": true,
           "docs": {
-            "default": "- A new provider is created per builder instance",
-            "remarks": "Use `TokenInjectableDockerBuilderProvider.getOrCreate(this)` to create\na singleton that is shared across all builders in the same stack.\n\nWhen omitted, each builder creates its own Lambdas (original behavior).",
+            "default": "- Per-stack singleton provider, created on first use.",
+            "remarks": "Pass `TokenInjectableDockerBuilderProvider.getOrCreate(this, { queryInterval })`\nif you need a non-default query interval. Otherwise, the construct will\ncall `getOrCreate(this)` itself and reuse the per-stack singleton.",
             "stability": "stable",
             "summary": "Shared provider for the custom resource Lambdas."
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 288
+            "filename": "src/builder.ts",
+            "line": 143
           },
           "name": "provider",
           "optional": true,
@@ -8964,18 +9028,43 @@
             "fqn": "token-injectable-docker-builder.TokenInjectableDockerBuilderProvider"
           }
         },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "[] - no replication",
+            "example": "['us-west-2', 'eu-west-1']",
+            "remarks": "The image is pushed to the primary\nregion's ECR as usual; ECR asynchronously replicates the same\n`repositoryName` + `imageTag` to each region listed here.\n\nConsumers in another region (a Lambda in `us-west-2` referencing an\nimage built in `us-east-1`) can use `dockerImageCodeFor(region)` or\n`containerImageFor(region)` to import the replicated image.\n\nThe custom resource waits for replication to complete before\nsignalling deploy-complete, so downstream stacks can safely deploy\nimmediately after.\n\n**Caveats:**\n- Cross-region replication is not supported between AWS partitions.\n- Replicas do **not** inherit the primary's encryption (defaults to\n  AES-256), lifecycle policies, or repository policies.\n- Replicated repositories persist on stack deletion — AWS does not\n  auto-delete them. Clean up manually via the ECR console / CLI if\n  needed.\n- Both the builder stack and any consumer stack in another region\n  must set `crossRegionReferences: true` for the image tag to flow.\n- Stacks must have a concrete region (`env: { account, region }`),\n  not the env-agnostic default.",
+            "stability": "stable",
+            "summary": "Additional AWS regions to replicate the built image to via ECR's native registry replication."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/builder.ts",
+            "line": 191
+          },
+          "name": "replicaRegions",
+          "optional": true,
+          "type": {
+            "collection": {
+              "elementtype": {
+                "primitive": "string"
+              },
+              "kind": "array"
+            }
+          }
+        },
         {
           "abstract": true,
           "docs": {
             "default": "false",
-            "remarks": "Because the log group is managed imperatively (not by CloudFormation),\nit survives stack rollbacks and preserves full build logs for debugging.\nA 7-day retention policy is applied so old logs auto-expire.\n\nSet to `false` after debugging to delete the log group and clean up.",
+            "remarks": "Survives stack rollbacks for debugging. 7-day retention.",
             "stability": "stable",
             "summary": "When `true`, creates a CloudWatch log group outside of CloudFormation (`/docker-builder/<projectName>`) and directs CodeBuild output there."
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 328
+            "filename": "src/builder.ts",
+            "line": 160
           },
           "name": "retainBuildLogs",
           "optional": true,
@@ -8986,15 +9075,14 @@
         {
           "abstract": true,
           "docs": {
-            "default": "- No security groups are attached.",
-            "remarks": "These define the network access rules for the CodeBuild project.",
+            "default": "- No security groups attached.",
             "stability": "stable",
-            "summary": "The security groups to attach to the CodeBuild project."
+            "summary": "Security groups attached to the CodeBuild project."
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 178
+            "filename": "src/builder.ts",
+            "line": 67
           },
           "name": "securityGroups",
           "optional": true,
@@ -9010,15 +9098,14 @@
         {
           "abstract": true,
           "docs": {
-            "default": "- All subnets in the VPC are used.",
-            "remarks": "Allows the user to select private, public, or isolated subnets.",
+            "default": "- All subnets in the VPC.",
             "stability": "stable",
-            "summary": "The subnet selection to specify which subnets to use within the VPC."
+            "summary": "Subnet selection within the VPC."
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 186
+            "filename": "src/builder.ts",
+            "line": 74
           },
           "name": "subnetSelection",
           "optional": true,
@@ -9029,15 +9116,14 @@
         {
           "abstract": true,
           "docs": {
-            "default": "- No VPC is attached, and the CodeBuild project will use public internet.",
-            "remarks": "If provided, the CodeBuild project will be launched within the specified VPC.",
+            "default": "- CodeBuild uses public internet.",
             "stability": "stable",
             "summary": "The VPC in which the CodeBuild project will be deployed."
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 170
+            "filename": "src/builder.ts",
+            "line": 60
           },
           "name": "vpc",
           "optional": true,
@@ -9046,7 +9132,7 @@
           }
         }
       ],
-      "symbolId": "src/index:TokenInjectableDockerBuilderProps"
+      "symbolId": "src/builder:TokenInjectableDockerBuilderProps"
     },
     "token-injectable-docker-builder.TokenInjectableDockerBuilderProvider": {
       "assembly": "token-injectable-docker-builder",
@@ -9059,8 +9145,8 @@
       "fqn": "token-injectable-docker-builder.TokenInjectableDockerBuilderProvider",
       "kind": "class",
       "locationInModule": {
-        "filename": "src/index.ts",
-        "line": 39
+        "filename": "src/provider.ts",
+        "line": 48
       },
       "methods": [
         {
@@ -9070,8 +9156,8 @@
             "summary": "Get or create the singleton provider for this stack."
           },
           "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 45
+            "filename": "src/provider.ts",
+            "line": 54
           },
           "name": "getOrCreate",
           "parameters": [
@@ -9102,8 +9188,8 @@
             "summary": "Grant the shared Lambdas permission to start builds for a specific CodeBuild project and pull/push to its ECR repository."
           },
           "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 110
+            "filename": "src/provider.ts",
+            "line": 137
           },
           "name": "registerProject",
           "parameters": [
@@ -9127,6 +9213,37 @@
               }
             }
           ]
+        },
+        {
+          "docs": {
+            "remarks": "Multiple builders contribute specs; the CR merges them into\na single registry-wide configuration on every deploy.\n\nAlso grants the `isComplete` Lambda permission to BatchGetImage on each\nreplica region's repo so it can poll for replication availability.",
+            "stability": "stable",
+            "summary": "Register a builder's replica regions with the singleton's replication-config custom resource."
+          },
+          "locationInModule": {
+            "filename": "src/provider.ts",
+            "line": 161
+          },
+          "name": "registerReplication",
+          "parameters": [
+            {
+              "name": "repoName",
+              "type": {
+                "primitive": "string"
+              }
+            },
+            {
+              "name": "replicaRegions",
+              "type": {
+                "collection": {
+                  "elementtype": {
+                    "primitive": "string"
+                  },
+                  "kind": "array"
+                }
+              }
+            }
+          ]
         }
       ],
       "name": "TokenInjectableDockerBuilderProvider",
@@ -9138,8 +9255,8 @@
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 53
+            "filename": "src/provider.ts",
+            "line": 67
           },
           "name": "serviceToken",
           "type": {
@@ -9147,7 +9264,7 @@
           }
         }
       ],
-      "symbolId": "src/index:TokenInjectableDockerBuilderProvider"
+      "symbolId": "src/provider:TokenInjectableDockerBuilderProvider"
     },
     "token-injectable-docker-builder.TokenInjectableDockerBuilderProviderProps": {
       "assembly": "token-injectable-docker-builder",
@@ -9159,8 +9276,8 @@
       "fqn": "token-injectable-docker-builder.TokenInjectableDockerBuilderProviderProps",
       "kind": "interface",
       "locationInModule": {
-        "filename": "src/index.ts",
-        "line": 23
+        "filename": "src/provider.ts",
+        "line": 32
       },
       "name": "TokenInjectableDockerBuilderProviderProps",
       "properties": [
@@ -9173,8 +9290,8 @@
           },
           "immutable": true,
           "locationInModule": {
-            "filename": "src/index.ts",
-            "line": 29
+            "filename": "src/provider.ts",
+            "line": 38
           },
           "name": "queryInterval",
           "optional": true,
@@ -9183,9 +9300,9 @@
           }
         }
       ],
-      "symbolId": "src/index:TokenInjectableDockerBuilderProviderProps"
+      "symbolId": "src/provider:TokenInjectableDockerBuilderProviderProps"
     }
   },
-  "version": "1.13.4",
-  "fingerprint": "L1ox5Rvu3CoKUlYIyP11zyArNKY7xbJKD/hBPMC9ToI="
+  "version": "2.0.0",
+  "fingerprint": "Gl+WrdapXYZ7IM70Nee/QkOa8/vCH2vPQ/Zdj13q9Fk="
 }