Coming from AWS CDK to Encore

AWS CDK applications use constructs to define AWS infrastructure and synthesize it into CloudFormation templates. Encore's TypeScript or Go SDK declarations instead describe the APIs, services, and infrastructure used by the backend. They form an application model that Encore uses for local development and deployment, while CDK can continue to manage AWS infrastructure outside that model.

For migration choices that apply to all infrastructure-as-code tools, see Coming from an IaC tool.

How it works

The following TypeScript examples define an object storage bucket in AWS CDK and Encore:

import * as s3 from "aws-cdk-lib/aws-s3";

const uploads = new s3.Bucket(this, "Uploads", {
  versioned: false,
});


import { Bucket } from "encore.dev/storage/objects";

export const uploads = new Bucket("uploads", { versioned: false });


import "encore.dev/storage/objects"

var Uploads = objects.NewBucket("uploads", objects.BucketConfig{Versioned: false})

The CDK construct contributes one or more AWS resources to a CloudFormation stack. The Encore declaration identifies a logical bucket used by the application. In a cloud environment, Encore can provision the bucket or connect the declaration to a supported existing bucket. During local development, Encore provides local development infrastructure.

Encore declarations are not CDK constructs. CDK construct code runs during synthesis and can generate an arbitrary CloudFormation graph. Encore uses static analysis, so primitive declarations must use literal names and appear where the parser can discover them.

How the concepts map

AWS CDK	Encore
App	No direct equivalent; an Encore application is derived from services, APIs, and resources in source
Stack	An environment is the closest deployment concept, but it is not a CloudFormation stack
L1, L2, or L3 construct	An Encore primitive when the application resource is supported; otherwise keep the construct in CDK
Construct tree	The application model records services, APIs, resources, and their usage relationships
Construct ID and logical ID	No direct equivalent; an Encore resource name identifies the logical application resource
Tokens and references	Application code imports and uses the logical resource object
Explicit dependencies	Usually derived from resource usage and service calls; no direct equivalent
Context and stack parameters	No single equivalent; infrastructure settings, secrets, and other application configuration are handled separately
CloudFormation output or cross-stack reference	No general equivalent; retain outputs for CDK-managed infrastructure
`cdk synth`	No direct equivalent; Encore builds derive and validate the application model
`cdk diff`	No direct equivalent; Encore Cloud provides infrastructure change workflows
`cdk deploy`	No direct equivalent; an Encore Cloud deployment provisions supported changes, while AWS infrastructure outside the application model remains in the CDK workflow

Encore Cloud environments hold deployment properties such as capacity, networking, and backups. Logical resource properties remain with the declaration. Sensitive application values use Encore TypeScript secrets or Go secrets.

Decide what remains in CDK

CDK and Encore can be used together. CDK commonly continues to manage:

AWS account and organization configuration
VPCs, DNS, and shared networking
infrastructure without an Encore primitive
resources shared with non-Encore systems
custom resources and organization-specific constructs
infrastructure whose topology is generated during CDK synthesis

Encore Cloud can provision supported application resources while CDK retains those areas. The application connects to CDK-managed infrastructure using the relevant AWS SDK or client. Store any sensitive connection details in Encore secrets.

For self-hosted deployments, CDK can provision all AWS infrastructure. An infra config file maps supported Encore declarations to those physical resources. See Configure infrastructure.

CloudFormation ownership and existing resources

CDK deploys through CloudFormation, so CloudFormation stack ownership remains relevant during migration. Encore does not read a CDK cloud assembly or adopt a CloudFormation stack as its application model.

Encore Cloud provides resource-specific workflows for connecting supported existing infrastructure:

This differs from cdk import. CDK import brings an existing AWS resource under CloudFormation management in a CDK stack. Encore's import workflow connects an Encore declaration to existing physical infrastructure. It does not convert the CDK construct tree into Encore declarations.

Avoid managing the same physical resource through an active CloudFormation stack and Encore. Before moving ownership, set the CDK resource's removal policy to RETAIN and deploy that change. Then remove the construct and deploy again so CloudFormation stops managing the resource without deleting it, as described in the CDK import guidance. Follow the relevant Encore import guide and verify the Encore environment before completing the handoff.

If CDK retains ownership, leave the construct and CloudFormation resource in place. Treat the resource as an external dependency of the Encore application.

Migrate incrementally

Choose one service and list the constructs and CloudFormation resources it depends on.
Map supported databases, Pub/Sub, object storage, caches, cron jobs, and secrets to TypeScript primitives or Go primitives.
Identify shared constructs, cross-stack references, custom resources, and unsupported AWS services that must remain in CDK.
Decide whether the target environment will use Encore Cloud or be self-hosted.
Add the Encore declarations and test with encore run and encore test.
For Encore Cloud, provision new resources or follow the supported import workflow. For self-hosting, retain CDK provisioning and map the resources through infra config.
Deploy and verify resource connectivity, data, IAM behavior, and rollback procedures.
Change CloudFormation ownership only after the Encore environment is verified.

Keep CloudFormation outputs and cross-stack references stable until all consumers have moved. Repeat the process for the next service.

Workflow differences

Encore validates statically discoverable resource declarations during the build and configures their deployment per environment. It does not replace CDK synthesis, CloudFormation stacks, or cdk diff. Keep unsupported, shared, and dynamically generated infrastructure in CDK, and migrate one ownership boundary at a time.

See Development workflow for local, preview, and production environments. For service-by-service application migration patterns, see Migrating an existing system to Encore.