Amplify Toolbox
    Preparing search index...

    Interface PipelineSynthConfig

    Configuration for the synth step (build + CDK synth).

    The synth step installs dependencies and runs cdk synth to produce the CloudFormation template. The pipeline is self-mutating: if the synth output changes the pipeline definition, it updates itself first.

    interface PipelineSynthConfig {
        buildImage?: IBuildImage;
        commands?: string[];
        computeType?: ComputeType;
        dockerEnabled?: boolean;
        env?: Record<string, string>;
        installCommands?: string[];
        partialBuildSpec?: BuildSpec | null;
        primaryOutputDirectory?: string;
    }
    Index

    Properties

    buildImage? commands? computeType? dockerEnabled? env? installCommands? partialBuildSpec? primaryOutputDirectory?

    Properties

    buildImage?: IBuildImage

    The CodeBuild build image to use for the synth step.

    The default image (Amazon Linux 2023 standard:5.0) includes Node 22 and Amazon Linux 2023. Override this if you need a different OS or runtime set.

    codebuild.LinuxBuildImage.AMAZON_LINUX_2023_5
    commands?: string[]

    Shell commands to run during the synth step.

    ['npm ci', 'npx cdk synth'] — installs dependencies and synthesizes the CDK app. Override if you need Node version upgrades, custom build steps, or a non-standard cdk.json app path. If your app requires Node 22+, prepend 'n 22' to commands or use installCommands.

    computeType?: ComputeType

    CodeBuild compute type for the synth step.

    Controls the CPU/memory allocation for the build environment. Increase this if you encounter OOM (exit code 137) during synth/bundling.

    • SMALL: 2 vCPU, 3 GB
    • MEDIUM: 4 vCPU, 7 GB
    • LARGE: 8 vCPU, 15 GB
    ComputeType.MEDIUM (7GB RAM, 4 vCPU) — sufficient for most apps with
    Lambda bundling + frontend builds. Use SMALL for trivial apps or LARGE for monorepos.
    dockerEnabled?: boolean

    Whether to enable Docker for the synth step.

    Required when your CDK app uses Docker image assets (e.g., Lambda container images, ECS task definitions with Dockerfile builds).

    false
    env?: Record<string, string>

    Environment variables available during synth.

    Note: NODE_OPTIONS is automatically prepended with --conditions=cdk (required for ESM conditional exports). Your custom NODE_OPTIONS will be appended after this flag.

    installCommands?: string[]

    Commands to run in the CodeBuild install phase (before synth commands).

    [] — no install commands. The default build image (Amazon Linux 2023 standard:5.0)
    includes Node 22. Set this if you need additional global tools or a different Node version.

    ['n 20'] — downgrade Node to version 20
    partialBuildSpec?: BuildSpec | null

    A partial CodeBuild BuildSpec merged into the synth step's generated buildspec.

    Use this to control the synth runtime declaratively, most commonly to pin the Node.js version via runtime-versions. It merges with (does not replace) the install/build commands generated from installCommands and commands, and is orthogonal to the NODE_OPTIONS environment variable injection (one configures the buildspec, the other sets an env var).

    Three behaviors, selected by the value you pass:

    • omitted (undefined): the synth step gets a default BuildSpec pinning the Node.js 22 runtime (see @default below). This is the recommended path.
    • null: explicit opt-out. No partialBuildSpec is injected at all, so the synth buildspec carries no runtime-versions block. Use this when you want to control the runtime yourself, for example by installing a Node version via installCommands (such as ['n 20']) or by relying on the build image's built-in runtime without any merged buildspec.
    • a BuildSpec: used as-is, replacing the Node.js 22 default.

    a BuildSpec declaring the Node.js 22 runtime: BuildSpec.fromObject({ phases: { install: { 'runtime-versions': { nodejs: 22 } } } }). Override with a BuildSpec to select a different runtime or add other buildspec-only settings, or pass null to disable the default entirely.

    synth: {
      partialBuildSpec: BuildSpec.fromObject({
        phases: { install: { 'runtime-versions': { nodejs: 20 } } },
      }),
    }

    synth: {
      partialBuildSpec: null,
      installCommands: ['n 20'], // or rely on the build image's default runtime
    }
    primaryOutputDirectory?: string

    Primary output directory for the CDK cloud assembly.

    Override this for monorepos where cdk synth outputs to a subdirectory (e.g., packages/infra/cdk.out).

    'cdk.out'

    Settings

    Member Visibility

    On This Page

    Properties