cdk refactor working example

[scornejob]

Has anyone managed to get cdk refactor to do anything at all? I'm following this guide with a simple change: the lambda replies hello world, but I still got some errors...

FWIW: I first deployed the stack from the example:

// original stack
const app = new cdk.App();
const myStack = new cdk.Stack(app, 'MyStack');

const bucket = new s3.Bucket(myStack, 'Bucket');
const distribution = new cloudfront.Distribution(myStack, 'Distribution', {
  defaultBehavior: { origin: new origins.S3Origin(bucket) }
});
const myFunction = new lambda.Function(myStack, 'Function', {
  runtime: lambda.Runtime.NODEJS_22_X,
  handler: 'index.handler',
  code: lambda.Code.fromInline(`
    exports.handler = async function(event) {
      console.log("Hello from Lambda!");
      return {
        statusCode: 200,
        body: "Hello from Lambda!"
      };
    };
  `)
});

Then, I had to deploy an empty stack (cdk refactor limitation). I also added the logicalIds to confirm my override file was ok (more on that later):

// intermediate stack: creates empty WebStack where resources will be moved
const app = new cdk.App();
const webStack = new cdk.Stack(app, 'WebStack');
const myStack = new cdk.Stack(app, 'MyStack');

const bucket = new s3.Bucket(myStack, 'Bucket');
// print the bucket logical id to use it in the overrides file
console.log(`Bucket logical ID: ${myStack.resolve((bucket.node.defaultChild as cdk.CfnElement).logicalId)}`);
const distribution = new cloudfront.Distribution(myStack, 'Distribution', {
  defaultBehavior: { origin: new origins.S3Origin(bucket) }
});
// print the distribution logical id to use it in the overrides file
console.log(`Distribution logical ID: ${myStack.resolve((distribution.node.defaultChild as cdk.CfnElement).logicalId)}`);

const myFunction = new lambda.Function(myStack, 'Function', {
  runtime: lambda.Runtime.NODEJS_22_X,
  handler: 'index.handler',
  code: lambda.Code.fromInline(`
    exports.handler = async function(event) {
      console.log("Hello from Lambda!");
      return {
        statusCode: 200,
        body: "Hello from Lambda!"
      };
    };
  `)
});

// Synthesize the app
app.synth();

And finally, made this stack, which is what I expect to refactor (haven't deployed tho, as refactor should do that):

// Refactored structure
const app = new cdk.App();

// New WebStack with the bucket and distribution
const webStack = new cdk.Stack(app, 'WebStack', { env: { account: "358135218535", region: "eu-central-1" }});
const bucket = new s3.Bucket(webStack, 'Bucket');
const distribution = new cloudfront.Distribution(webStack, 'Distribution', {
  defaultBehavior: { origin: new origins.S3Origin(bucket) }
});

// Original MyStack with just the function
const myStack = new cdk.Stack(app, 'MyStack', { env: { account: "358135218535", region: "eu-central-1" }});
const myFunction = new lambda.Function(myStack, 'Function', {
  runtime: lambda.Runtime.NODEJS_22_X,
  handler: 'index.handler',
  code: lambda.Code.fromInline(`
    exports.handler = async function(event) {
      console.log("Hello from Lambda!");
      return {
        statusCode: 200,
        body: "Hello from Lambda!"
      };
    };
  `)
});

// Synthesize the app
app.synth();

I tried a cdk refactor --unstable=refactor, and got an error:

❯ cdk refactor --unstable=refactor                                
[WARNING] aws-cdk-lib.aws_cloudfront_origins.S3Origin is deprecated.
  Use `S3BucketOrigin` or `S3StaticWebsiteOrigin` instead.
  This API will be removed in the next major release.
[WARNING] aws-cdk-lib.aws_cloudfront_origins.S3Origin#bind is deprecated.
  Use `S3BucketOrigin` or `S3StaticWebsiteOrigin` instead.
  This API will be removed in the next major release.
✨  Synthesis time: 1.07s
aws://358135218535/eu-central-1

❌  Refactor failed: A refactor operation cannot add, remove or update resources. Only resource moves and renames are allowed.
The following resources are present only in the AWS environment:
  - MyStack/Bucket/Policy/Resource
  - MyStack/Distribution/Origin1/S3Origin/Resource
  - MyStack/Distribution/Resource

The following resources are present only in your CDK application:
  - WebStack/Bucket/Policy/Resource
  - WebStack/Distribution/Origin1/S3Origin/Resource
  - WebStack/Distribution/Resource

The following stacks were used in the comparison:
  - Deployed: MyStack, WebStack
  - Local: MyStack, WebStack

Hint: by default, only deployed stacks that have the same name as a local stack are included.
If you want to include additional deployed stacks for comparison, re-run the command with the option '--additional-stack-name=<STACK>' for each stack.

So then I made an override.json file, as those three resource it complains about are actually part of those I want to move (the bucket and the CF distro):

{
    "environments": [
        {
            "account": "MYACCOUNT",
            "region": "a-valid-region",
            "resources": {
                "MyStack.Bucket83908E77.BucketPolicyE9A3008A": "WebStack.Bucket83908E77.BucketPolicyE9A3008A",
                "MyStack.Distribution830FAC52": "WebStack.Distribution830FAC52",
                "MyStack.Distribution830FAC52.Origin1.S3Origin.DistributionOrigin1S3Origin5F5C0696": "WebStack.Distribution830FAC52.Origin1.S3Origin.DistributionOrigin1S3Origin5F5C0696"
            }
        }
    ]
}

But using this override file yields the same result as before. Is there any working example to try this out? Has anyone get this to work?

[Sagargupta16]

cdk refactor is relatively new and has some rough edges. Here is what typically goes wrong and a working example.

Common issues

1. Must deploy the original stack first - cdk refactor compares your CDK code against the deployed CloudFormation state. If the stack is not deployed, there is nothing to compare against.

2. The refactor mapping file - You need to create a cdk.context.json or pass mappings explicitly. The CLI does not auto-detect renames.

Working example

Step 1: Deploy original stack

const app = new cdk.App();
const myStack = new cdk.Stack(app, "MyStack");
const bucket = new s3.Bucket(myStack, "Bucket");
const distribution = new cloudfront.Distribution(myStack, "Distribution", {
  defaultBehavior: { origin: new origins.S3BucketOrigin(bucket) },
});

cdk deploy MyStack

Step 2: Refactor the code (move into a construct)

class WebsiteConstruct extends Construct {
  constructor(scope: Construct, id: string) {
    super(scope, id);
    const bucket = new s3.Bucket(this, "Bucket");
    new cloudfront.Distribution(this, "Distribution", {
      defaultBehavior: { origin: new origins.S3BucketOrigin(bucket) },
    });
  }
}

const app = new cdk.App();
const myStack = new cdk.Stack(app, "MyStack");
new WebsiteConstruct(myStack, "Website");

Step 3: Run refactor

cdk refactor --dry-run

This should show the mapping:

• MyStack/Bucket -> MyStack/Website/Bucket
• MyStack/Distribution -> MyStack/Website/Distribution

If it works in dry-run:

cdk refactor
cdk deploy MyStack

Troubleshooting

• If you get No changes detected - make sure you deployed the original version first
• If you get resource replacement warnings - the logical IDs changed in a way CDK cannot safely map. You may need to add explicit overrideLogicalId() calls
• Check that your CDK CLI version matches your aws-cdk-lib version - version mismatches cause issues with refactor

What errors are you seeing specifically? The error message would help narrow it down.