# API Reference
## Constructs
### TokenInjectableDockerBuilder
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.
#### Initializers
```typescript
import { TokenInjectableDockerBuilder } from 'token-injectable-docker-builder'
new TokenInjectableDockerBuilder(scope: Construct, id: string, props: TokenInjectableDockerBuilderProps)
```
| **Name** | **Type** | **Description** |
| --- | --- | --- |
| scope | constructs.Construct | *No description.* |
| id | string | *No description.* |
| props | TokenInjectableDockerBuilderProps | *No description.* |
---
##### `scope`Required
- *Type:* constructs.Construct
---
##### `id`Required
- *Type:* string
---
##### `props`Required
- *Type:* TokenInjectableDockerBuilderProps
---
#### Methods
| **Name** | **Description** |
| --- | --- |
| toString | Returns a string representation of this construct. |
| with | Applies one or more mixins to this construct. |
| containerImageFor | Import the replicated repository as an ECS-compatible `ContainerImage` in a consumer scope (typically a stack in `region`). |
| dockerImageCodeFor | Import the replicated repository as a Lambda-compatible `DockerImageCode` in a consumer scope (typically a stack in `region`). |
| repositoryUriFor | Format the ECR repository URI for a given region. |
---
##### `toString`
```typescript
public toString(): string
```
Returns a string representation of this construct.
##### `with`
```typescript
public with(mixins: ...IMixin[]): IConstruct
```
Applies one or more mixins to this construct.
Mixins are applied in order. The list of constructs is captured at the
start of the call, so constructs added by a mixin will not be visited.
Use multiple `with()` calls if subsequent mixins should apply to added
constructs.
###### `mixins`Required
- *Type:* ...constructs.IMixin[]
The mixins to apply.
---
##### `containerImageFor`
```typescript
public containerImageFor(scope: Construct, region: string): ContainerImage
```
Import the replicated repository as an ECS-compatible `ContainerImage` in a consumer scope (typically a stack in `region`).
The consumer's stack must have `crossRegionReferences: true` when
`region` differs from the builder's region.
Cross-stack consumers (same region or different region) receive
`imageTagPlain` (a synth-time string) rather than `imageTag` (a CFN
token). Using the token would cause CDK to auto-create either a
`CrossRegionExportWriter` (cross-region) or a cross-stack
`Fn::Export` / `Fn::ImportValue` (same-region). Both wedge any deploy
that changes the imageTag value, because CFN refuses to "update an
export in use" or runs the writer's "Some exports have changed" check.
Same-stack callers keep the token form so the Lambda still has a CFN
dependency on the build trigger CR.
###### `scope`Required
- *Type:* constructs.Construct
---
###### `region`Required
- *Type:* string
---
##### `dockerImageCodeFor`
```typescript
public dockerImageCodeFor(scope: Construct, region: string): DockerImageCode
```
Import the replicated repository as a Lambda-compatible `DockerImageCode` in a consumer scope (typically a stack in `region`).
The consumer's stack must have `crossRegionReferences: true` when
`region` differs from the builder's region.
Cross-stack consumers (same region or different region) receive
`imageTagPlain` (a synth-time string) rather than `imageTag` (a CFN
token). See `containerImageFor` for the rationale.
###### `scope`Required
- *Type:* constructs.Construct
---
###### `region`Required
- *Type:* string
---
##### `repositoryUriFor`
```typescript
public repositoryUriFor(region: string): string
```
Format the ECR repository URI for a given region.
The region must
be either the primary region or one of `replicaRegions`.
###### `region`Required
- *Type:* string
---
#### Static Functions
| **Name** | **Description** |
| --- | --- |
| isConstruct | Checks if `x` is a construct. |
---
##### `isConstruct`
```typescript
import { TokenInjectableDockerBuilder } from 'token-injectable-docker-builder'
TokenInjectableDockerBuilder.isConstruct(x: any)
```
Checks if `x` is a construct.
Use this method instead of `instanceof` to properly detect `Construct`
instances, even when the construct library is symlinked.
Explanation: in JavaScript, multiple copies of the `constructs` library on
disk are seen as independent, completely different libraries. As a
consequence, the class `Construct` in each copy of the `constructs` library
is seen as a different class, and an instance of one class will not test as
`instanceof` the other class. `npm install` will not create installations
like this, but users may manually symlink construct libraries together or
use a monorepo tool: in those cases, multiple copies of the `constructs`
library can be accidentally installed, and `instanceof` will behave
unpredictably. It is safest to avoid using `instanceof`, and using
this type-testing method instead.
###### `x`Required
- *Type:* any
Any object.
---
#### Properties
| **Name** | **Type** | **Description** |
| --- | --- | --- |
| node | constructs.Node | The tree node. |
| containerImage | aws-cdk-lib.aws_ecs.ContainerImage | ECS-compatible container image reference (primary region). |
| dockerImageCode | aws-cdk-lib.aws_lambda.DockerImageCode | Lambda-compatible DockerImageCode reference (primary region). |
| imageTag | string | The resolved image tag (CFN token; available at deploy time). |
| imageTagPlain | string | The deterministic image tag as a plain synth-time string (no CFN token). |
| repositoryName | string | The ECR repository name — preserved across replica regions. |
---
##### `node`Required
```typescript
public readonly node: Node;
```
- *Type:* constructs.Node
The tree node.
---
##### `containerImage`Required
```typescript
public readonly containerImage: ContainerImage;
```
- *Type:* aws-cdk-lib.aws_ecs.ContainerImage
ECS-compatible container image reference (primary region).
---
##### `dockerImageCode`Required
```typescript
public readonly dockerImageCode: DockerImageCode;
```
- *Type:* aws-cdk-lib.aws_lambda.DockerImageCode
Lambda-compatible DockerImageCode reference (primary region).
---
##### `imageTag`Required
```typescript
public readonly imageTag: string;
```
- *Type:* string
The resolved image tag (CFN token; available at deploy time).
Safe to use anywhere the consumer is in the **same region** as the
builder (same stack or different stack). For cross-region consumers
use `imageTagPlain` — `imageTag` would trigger CDK's
`CrossRegionExportWriter` and wedge on any tag change.
---
##### `imageTagPlain`Required
```typescript
public readonly imageTagPlain: string;
```
- *Type:* string
The deterministic image tag as a plain synth-time string (no CFN token).
Same value as `imageTag` but resolved immediately — useful for cross-region
consumers, where the CFN-token form would trigger CDK to auto-create a
`CrossRegionExportWriter`. That writer has an over-strict safety check
that fails any update where the tag value changes (i.e. every real code
change), wedging the stack in `UPDATE_ROLLBACK_FAILED`.
`containerImageFor` and `dockerImageCodeFor` use this string automatically
when the consumer region differs from the primary region, so callers
normally don't reference this property directly.
---
##### `repositoryName`Required
```typescript
public readonly repositoryName: string;
```
- *Type:* string
The ECR repository name — preserved across replica regions.
---
### TokenInjectableDockerBuilderProvider
Shared provider for `TokenInjectableDockerBuilder` instances.
Creates the onEvent and isComplete Lambda functions once per stack.
Each builder instance registers its CodeBuild project ARN so the
shared Lambdas have permission to start builds and read logs.
#### Methods
| **Name** | **Description** |
| --- | --- |
| toString | Returns a string representation of this construct. |
| with | Applies one or more mixins to this construct. |
| registerProject | Grant the shared Lambdas permission to start builds for a specific CodeBuild project and pull/push to its ECR repository. |
| registerReplication | Register a builder's replica regions with the singleton's replication-config custom resource. |
---
##### `toString`
```typescript
public toString(): string
```
Returns a string representation of this construct.
##### `with`
```typescript
public with(mixins: ...IMixin[]): IConstruct
```
Applies one or more mixins to this construct.
Mixins are applied in order. The list of constructs is captured at the
start of the call, so constructs added by a mixin will not be visited.
Use multiple `with()` calls if subsequent mixins should apply to added
constructs.
###### `mixins`Required
- *Type:* ...constructs.IMixin[]
The mixins to apply.
---
##### `registerProject`
```typescript
public registerProject(project: Project, ecrRepo: Repository, encryptionKey?: Key): void
```
Grant the shared Lambdas permission to start builds for a specific CodeBuild project and pull/push to its ECR repository.
###### `project`Required
- *Type:* aws-cdk-lib.aws_codebuild.Project
---
###### `ecrRepo`Required
- *Type:* aws-cdk-lib.aws_ecr.Repository
---
###### `encryptionKey`Optional
- *Type:* aws-cdk-lib.aws_kms.Key
---
##### `registerReplication`
```typescript
public registerReplication(repoName: string, replicaRegions: string[]): void
```
Register a builder's replica regions with the singleton's replication-config custom resource.
Multiple builders contribute specs; the CR merges them into
a single registry-wide configuration on every deploy.
Also grants the `isComplete` Lambda permission to BatchGetImage on each
replica region's repo so it can poll for replication availability.
###### `repoName`Required
- *Type:* string
---
###### `replicaRegions`Required
- *Type:* string[]
---
#### Static Functions
| **Name** | **Description** |
| --- | --- |
| isConstruct | Checks if `x` is a construct. |
| getOrCreate | Get or create the singleton provider for this stack. |
---
##### `isConstruct`
```typescript
import { TokenInjectableDockerBuilderProvider } from 'token-injectable-docker-builder'
TokenInjectableDockerBuilderProvider.isConstruct(x: any)
```
Checks if `x` is a construct.
Use this method instead of `instanceof` to properly detect `Construct`
instances, even when the construct library is symlinked.
Explanation: in JavaScript, multiple copies of the `constructs` library on
disk are seen as independent, completely different libraries. As a
consequence, the class `Construct` in each copy of the `constructs` library
is seen as a different class, and an instance of one class will not test as
`instanceof` the other class. `npm install` will not create installations
like this, but users may manually symlink construct libraries together or
use a monorepo tool: in those cases, multiple copies of the `constructs`
library can be accidentally installed, and `instanceof` will behave
unpredictably. It is safest to avoid using `instanceof`, and using
this type-testing method instead.
###### `x`Required
- *Type:* any
Any object.
---
##### `getOrCreate`
```typescript
import { TokenInjectableDockerBuilderProvider } from 'token-injectable-docker-builder'
TokenInjectableDockerBuilderProvider.getOrCreate(scope: Construct, props?: TokenInjectableDockerBuilderProviderProps)
```
Get or create the singleton provider for this stack.
All `TokenInjectableDockerBuilder` instances in the same stack
share a single pair of Lambda functions.
###### `scope`Required
- *Type:* constructs.Construct
---
###### `props`Optional
- *Type:* TokenInjectableDockerBuilderProviderProps
---
#### Properties
| **Name** | **Type** | **Description** |
| --- | --- | --- |
| node | constructs.Node | The tree node. |
| serviceToken | string | The service token used by CustomResource instances. |
---
##### `node`Required
```typescript
public readonly node: Node;
```
- *Type:* constructs.Node
The tree node.
---
##### `serviceToken`Required
```typescript
public readonly serviceToken: string;
```
- *Type:* string
The service token used by CustomResource instances.
---
## Structs
### TokenInjectableDockerBuilderProps
Properties for the `TokenInjectableDockerBuilder` construct.
#### Initializer
```typescript
import { TokenInjectableDockerBuilderProps } from 'token-injectable-docker-builder'
const tokenInjectableDockerBuilderProps: TokenInjectableDockerBuilderProps = { ... }
```
#### Properties
| **Name** | **Type** | **Description** |
| --- | --- | --- |
| path | string | The path to the directory containing the Dockerfile or source code. |
| buildArgs | {[ key: string ]: string} | Build arguments to pass to the Docker build process. |
| buildLogGroup | aws-cdk-lib.aws_logs.ILogGroup | CloudWatch log group for CodeBuild build logs. |
| cacheDisabled | boolean | When `true`, disables Docker layer caching. |
| dockerLoginSecretArn | string | The ARN of the AWS Secrets Manager secret containing Docker login credentials. |
| ecrPullThroughCachePrefixes | string[] | ECR pull-through cache repository prefixes to grant pull access to. |
| exclude | string[] | File paths in the Docker directory to exclude from the build asset. |
| file | string | Name of the Dockerfile (passed as `-f`). |
| installCommands | string[] | Custom commands to run during the install phase of CodeBuild. |
| kmsEncryption | boolean | Whether to enable KMS encryption for the ECR repository. |
| platform | string | Target platform for the Docker image. |
| preBuildCommands | string[] | Custom commands to run during the pre_build phase of CodeBuild. |
| provider | TokenInjectableDockerBuilderProvider | Shared provider for the custom resource Lambdas. |
| replicaRegions | string[] | Additional AWS regions to replicate the built image to via ECR's native registry replication. |
| retainBuildLogs | boolean | When `true`, creates a CloudWatch log group outside of CloudFormation (`/docker-builder/`) and directs CodeBuild output there. |
| securityGroups | aws-cdk-lib.aws_ec2.ISecurityGroup[] | Security groups attached to the CodeBuild project. |
| subnetSelection | aws-cdk-lib.aws_ec2.SubnetSelection | Subnet selection within the VPC. |
| vpc | aws-cdk-lib.aws_ec2.IVpc | The VPC in which the CodeBuild project will be deployed. |
---
##### `path`Required
```typescript
public readonly path: string;
```
- *Type:* string
The path to the directory containing the Dockerfile or source code.
---
##### `buildArgs`Optional
```typescript
public readonly buildArgs: {[ key: string ]: string};
```
- *Type:* {[ key: string ]: string}
Build arguments to pass to the Docker build process.
These are transformed into `--build-arg KEY=VALUE` flags.
---
*Example*
```typescript
{
TOKEN: 'my-secret-token',
ENV: 'production'
}
```
##### `buildLogGroup`Optional
```typescript
public readonly buildLogGroup: ILogGroup;
```
- *Type:* aws-cdk-lib.aws_logs.ILogGroup
- *Default:* CodeBuild default logging.
CloudWatch log group for CodeBuild build logs.
---
##### `cacheDisabled`Optional
```typescript
public readonly cacheDisabled: boolean;
```
- *Type:* boolean
- *Default:* false
When `true`, disables Docker layer caching.
---
##### `dockerLoginSecretArn`Optional
```typescript
public readonly dockerLoginSecretArn: string;
```
- *Type:* string
- *Default:* No Docker Hub login.
The ARN of the AWS Secrets Manager secret containing Docker login credentials.
The secret must store a JSON object: `{"username":"...","password":"..."}`.
Must be in the same region as the stack.
---
##### `ecrPullThroughCachePrefixes`Optional
```typescript
public readonly ecrPullThroughCachePrefixes: string[];
```
- *Type:* string[]
- *Default:* No pull-through cache access.
ECR pull-through cache repository prefixes to grant pull access to.
---
*Example*
```typescript
['docker-hub', 'ghcr']
```
##### `exclude`Optional
```typescript
public readonly exclude: string[];
```
- *Type:* string[]
- *Default:* No file path exclusions.
File paths in the Docker directory to exclude from the build asset.
Falls back to `.dockerignore` if present.
---
##### `file`Optional
```typescript
public readonly file: string;
```
- *Type:* string
- *Default:* 'Dockerfile'
Name of the Dockerfile (passed as `-f`).
---
*Example*
```typescript
'Dockerfile.production'
```
##### `installCommands`Optional
```typescript
public readonly installCommands: string[];
```
- *Type:* string[]
- *Default:* No additional install commands.
Custom commands to run during the install phase of CodeBuild.
---
##### `kmsEncryption`Optional
```typescript
public readonly kmsEncryption: boolean;
```
- *Type:* boolean
- *Default:* false
Whether to enable KMS encryption for the ECR repository.
---
##### `platform`Optional
```typescript
public readonly platform: string;
```
- *Type:* string
- *Default:* 'linux/amd64'
Target platform for the Docker image.
---
##### `preBuildCommands`Optional
```typescript
public readonly preBuildCommands: string[];
```
- *Type:* string[]
- *Default:* No additional pre-build commands.
Custom commands to run during the pre_build phase of CodeBuild.
---
##### `provider`Optional
```typescript
public readonly provider: TokenInjectableDockerBuilderProvider;
```
- *Type:* TokenInjectableDockerBuilderProvider
- *Default:* Per-stack singleton provider, created on first use.
Shared provider for the custom resource Lambdas.
Pass `TokenInjectableDockerBuilderProvider.getOrCreate(this, { queryInterval })`
if you need a non-default query interval. Otherwise, the construct will
call `getOrCreate(this)` itself and reuse the per-stack singleton.
---
##### `replicaRegions`Optional
```typescript
public readonly replicaRegions: string[];
```
- *Type:* string[]
- *Default:* [] - no replication
Additional AWS regions to replicate the built image to via ECR's native registry replication.
The image is pushed to the primary
region's ECR as usual; ECR asynchronously replicates the same
`repositoryName` + `imageTag` to each region listed here.
Consumers in another region (a Lambda in `us-west-2` referencing an
image built in `us-east-1`) can use `dockerImageCodeFor(region)` or
`containerImageFor(region)` to import the replicated image.
The custom resource waits for replication to complete before
signalling deploy-complete, so downstream stacks can safely deploy
immediately after.
**Caveats:**
- Cross-region replication is not supported between AWS partitions.
- Replicas do **not** inherit the primary's encryption (defaults to
AES-256), lifecycle policies, or repository policies.
- Replicated repositories persist on stack deletion — AWS does not
auto-delete them. Clean up manually via the ECR console / CLI if
needed.
- Both the builder stack and any consumer stack in another region
must set `crossRegionReferences: true` for the image tag to flow.
- Stacks must have a concrete region (`env: { account, region }`),
not the env-agnostic default.
---
*Example*
```typescript
['us-west-2', 'eu-west-1']
```
##### `retainBuildLogs`Optional
```typescript
public readonly retainBuildLogs: boolean;
```
- *Type:* boolean
- *Default:* false
When `true`, creates a CloudWatch log group outside of CloudFormation (`/docker-builder/`) and directs CodeBuild output there.
Survives stack rollbacks for debugging. 7-day retention.
---
##### `securityGroups`Optional
```typescript
public readonly securityGroups: ISecurityGroup[];
```
- *Type:* aws-cdk-lib.aws_ec2.ISecurityGroup[]
- *Default:* No security groups attached.
Security groups attached to the CodeBuild project.
---
##### `subnetSelection`Optional
```typescript
public readonly subnetSelection: SubnetSelection;
```
- *Type:* aws-cdk-lib.aws_ec2.SubnetSelection
- *Default:* All subnets in the VPC.
Subnet selection within the VPC.
---
##### `vpc`Optional
```typescript
public readonly vpc: IVpc;
```
- *Type:* aws-cdk-lib.aws_ec2.IVpc
- *Default:* CodeBuild uses public internet.
The VPC in which the CodeBuild project will be deployed.
---
### TokenInjectableDockerBuilderProviderProps
Options for creating a `TokenInjectableDockerBuilderProvider`.
#### Initializer
```typescript
import { TokenInjectableDockerBuilderProviderProps } from 'token-injectable-docker-builder'
const tokenInjectableDockerBuilderProviderProps: TokenInjectableDockerBuilderProviderProps = { ... }
```
#### Properties
| **Name** | **Type** | **Description** |
| --- | --- | --- |
| queryInterval | aws-cdk-lib.Duration | How often the provider polls for build completion. |
---
##### `queryInterval`Optional
```typescript
public readonly queryInterval: Duration;
```
- *Type:* aws-cdk-lib.Duration
- *Default:* Duration.seconds(30)
How often the provider polls for build completion.
---