Migrating from Serverless Framework to AWS CDK: Part 1 - Why Make the Switch?

When Serverless Framework introduced paid licensing, many teams started evaluating alternatives. After working with both tools, I learned that the decision goes deeper than just licensing costs - it's about infrastructure as code philosophy, type safety, and long-term maintainability.

This migration taught me valuable lessons about when each tool excels and what the transition actually involves. Rather than another theoretical comparison, this series focuses on practical migration patterns and the real trade-offs you'll encounter.

This six-part series covers the complete migration process:

• Part 1: Why migrate? Understanding the trade-offs (this post)
• Part 2: Setting up your CDK environment and project structure
• Part 3: Migrating Lambda functions and API Gateway
• Part 4: Database resources and environment management
• Part 5: Authentication, authorization, and IAM
• Part 6: Migration strategies and best practices

Understanding the Migration Motivations#

Migrating infrastructure tools isn't just about licensing costs. Here are the key factors that typically drive teams toward CDK:

Direct Cost Considerations#

Serverless Framework licensing (for teams using Pro features):

• Per-deployment pricing model
• Scaling costs with team growth
• Additional features behind paid tiers

CDK approach:

• No licensing fees (part of AWS CLI)
• Infrastructure as standard application code
• Native AWS service support

Hidden Operational Costs#

Working with both tools revealed several operational differences:

• YAML maintenance: Configuration syntax can become complex
• Plugin dependencies: Third-party plugin compatibility issues
• Cross-service references: String-based references vs. typed objects
• Debugging: Runtime vs. compile-time error detection

These factors matter more than direct costs for most applications.

Key Technical Differences That Matter#

Through practical experience, several technical differences became apparent that influence the migration decision:

1. Configuration vs. Code#

Serverless Framework approach (YAML configuration):

# serverless.ymlprovider:  environment:    STRIPE_API_KEY: ${env:STRIPE_API_KEY}    STRIPE_WEBHOOK_SECRET: ${env:STRIPE_WEBHOOK_SECRET}

CDK approach (TypeScript code):

// Environment variables are validated at compile timeconst webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;if (!webhookSecret) {  throw new Error('STRIPE_WEBHOOK_SECRET environment variable required');}

Key insight: Configuration typos can reach production with YAML, while TypeScript catches issues at compile time.

2. Plugin Dependencies vs. Native Integration#

Serverless Framework relies on community plugins for advanced features:

plugins:  - serverless-webpack  - serverless-offline  - serverless-step-functions
custom:  webpack:    webpackConfig: webpack.config.js

CDK provides native constructs for AWS services:

// Native bundling and service integrationconst bundling = {  target: 'node20',  minify: true,  sourceMap: true,};

Learning: Plugin compatibility can become a maintenance burden during Node.js upgrades.

3. Cross-Stack References#

Serverless Framework uses CloudFormation exports and string interpolation:

# auth-service/serverless.ymlprovider:  environment:    USER_TABLE_ARN: ${cf:database-stack-${opt:stage}.UserTableArn}

CDK enables type-safe object references:

// Direct object references with compile-time validationconst authStack = new AuthStack(this, 'AuthStack', {  userTable: databaseStack.userTable, // TypeScript ensures this exists});

Benefit: Refactoring becomes safer when dependencies are explicit and type-checked.

The TypeScript Infrastructure Advantage#

Moving from YAML configuration to TypeScript code brings several advantages:

Serverless Framework (YAML configuration):

# serverless.ymlprovider:  name: aws  runtime: nodejs20.x  environment:    TABLE_NAME: ${self:service}-${opt:stage}-users
functions:  createUser:    handler: src/handlers/users.create    events:      - http:          path: users          method: post          cors: true

CDK (TypeScript code):

// lib/api-stack.tsimport { RestApi, LambdaIntegration } from 'aws-cdk-lib/aws-apigateway';import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
const createUserFn = new NodejsFunction(this, 'CreateUserFunction', {  entry: 'src/handlers/users.ts',  handler: 'create',  environment: {    TABLE_NAME: userTable.tableName,  },});
// Type-safe integrationconst api = new RestApi(this, 'UserApi');api.root.addResource('users').addMethod('POST',  new LambdaIntegration(createUserFn));

Benefits include:

• Compile-time error detection
• IDE autocompletion
• Refactoring support
• Type-safe environment variables

Native AWS Service Integration#

Serverless Framework requires plugins for advanced AWS services:

plugins:  - serverless-step-functions  - serverless-appsync-plugin  - serverless-plugin-aws-alerts
custom:  alerts:    stages:      - production    topics:      alarm:        topic: ${self:service}-${opt:stage}-alerts

CDK provides native constructs for all AWS services:

import { StateMachine } from 'aws-cdk-lib/aws-stepfunctions';import { LambdaInvoke } from 'aws-cdk-lib/aws-stepfunctions-tasks';import { GraphqlApi } from 'aws-cdk-lib/aws-appsync';import { Alarm } from 'aws-cdk-lib/aws-cloudwatch';
// Direct service integration without pluginsconst workflow = new StateMachine(this, 'UserWorkflow', {  definition: new LambdaInvoke(this, 'ProcessUser', {    lambdaFunction: processUserFn,  }),});
const api = new GraphqlApi(this, 'UserGraphQL', {  name: 'user-api',  schema: SchemaFile.fromAsset('schema.graphql'),});

Infrastructure Composition and Reusability#

Serverless Framework uses includes and variables:

# serverless.ymlcustom:  userTableConfig: ${file(./config/tables.yml):userTable}
resources:  Resources:    UserTable: ${self:custom.userTableConfig}

CDK enables true object-oriented infrastructure:

// lib/constructs/serverless-api.tsexport class ServerlessApi extends Construct {  public readonly api: RestApi;  public readonly functions: Map<string, NodejsFunction>;
  constructor(scope: Construct, id: string, props: ServerlessApiProps) {    super(scope, id);
    // Encapsulated, reusable infrastructure patterns    this.api = new RestApi(this, 'Api', {      restApiName: props.apiName,      deployOptions: this.createDeployOptions(props.stage),    });
    this.functions = this.createFunctions(props.routes);    this.setupRoutes(props.routes);    this.setupAlarms(props.monitoring);  }}
// Usage across multiple stacksnew ServerlessApi(this, 'UserApi', {  apiName: 'users',  routes: userRoutes,  monitoring: productionMonitoring,});

Testing Infrastructure#

Serverless Framework testing typically involves:

• Mocking framework behavior
• Testing deployed resources
• Limited unit testing options

CDK enables comprehensive infrastructure testing:

// test/api-stack.test.tsimport { Template } from 'aws-cdk-lib/assertions';
test('API Gateway has CORS enabled', () => {  const template = Template.fromStack(stack);
  template.hasResourceProperties('AWS::ApiGateway::Method', {    Integration: {      IntegrationResponses: [{        ResponseParameters: {          'method.response.header.Access-Control-Allow-Origin': "'*'",        },      }],    },  });});
test('Lambda has correct environment variables', () => {  template.hasResourceProperties('AWS::Lambda::Function', {    Environment: {      Variables: {        TABLE_NAME: { Ref: Match.anyValue() },        STAGE: 'production',      },    },  });});

When Each Tool Excels#

Choose CDK When You Need:#

1. Complex AWS service integration - Step Functions, EventBridge, AppSync
2. Shared infrastructure patterns - Reusable constructs across teams
3. Fine-grained control - Custom CloudFormation resources
4. Strong typing - TypeScript throughout your stack
5. Infrastructure testing - Unit and integration tests for IaC
6. Large team coordination - Explicit dependencies and interfaces

Stay with Serverless Framework When:#

1. Simple Lambda + API Gateway - Basic CRUD APIs
2. Existing plugin ecosystem - Heavy reliance on community plugins
3. Team YAML preference - Developers uncomfortable with TypeScript
4. Quick prototypes - Rapid proof-of-concepts
5. Small applications - Minimal infrastructure complexity

Migration Complexity Assessment#

Before migrating, evaluate your current setup:

interface MigrationComplexity {  functionCount: number;  customResources: boolean;  plugins: string[];  environments: number;  cicdIntegration: boolean;}
function assessMigrationEffort(current: MigrationComplexity): string {  const pluginComplexity = current.plugins.filter(p =>    !['serverless-offline', 'serverless-webpack'].includes(p)  ).length;
  const score =    current.functionCount * 0.5 +    (current.customResources ? 20 : 0) +    pluginComplexity * 10 +    current.environments * 5 +    (current.cicdIntegration ? 15 : 0);
  if (score < 30) return 'Low - 1-2 weeks';  if (score < 60) return 'Medium - 2-4 weeks';  return 'High - 1-2 months';}

Migration Decision Framework#

Based on experience with both tools, here's a practical framework for evaluating migration:

Technical Assessment#

Current infrastructure complexity:

• Number of Lambda functions and services
• Custom resources and CloudFormation usage
• Cross-service dependencies
• Plugin dependencies and maintenance overhead

Team Readiness#

Skill evaluation:

• TypeScript experience level
• Infrastructure as code familiarity
• Available learning time
• Comfort with programmatic infrastructure

Migration Planning#

Risk mitigation strategies:

• Gradual migration vs. full cutover
• Rollback procedures and testing
• Parallel infrastructure during transition
• Team training and knowledge transfer

Expected Benefits#

Realistic outcome expectations:

• Improved developer experience with IDE support
• Better error detection at compile time
• Simplified cross-service references
• Enhanced testing capabilities for infrastructure

Migration Readiness Checklist#

Before starting a migration, consider these factors:

Technical Readiness#

• Team has TypeScript experience or learning time
• Current infrastructure is well-documented
• Plugin dependencies are understood and replaceable
• Testing strategy exists for infrastructure changes

Organizational Readiness#

• Migration timeline aligns with business goals
• Rollback procedures are defined
• Knowledge transfer plan exists
• Migration complexity is appropriate for team size

When NOT to Migrate#

Stick with Serverless Framework if:

1. Limited TypeScript experience - The learning curve may impact delivery
2. Simple, stable applications - Migration overhead may not be justified
3. Heavy plugin dependencies - Ensure CDK alternatives exist
4. Time constraints - Migration requires dedicated focus and time

What's Next#

Once you've decided to migrate, the real work begins: setting up a CDK project structure that supports safe, gradual migration.

In Part 2, I'll cover the practical setup steps that enable successful migration. We'll explore project architecture patterns, development workflows, and environment configuration that make the transition manageable.

The technical migration is often easier than the process challenges - coordinating team efforts, maintaining development velocity, and ensuring production stability throughout the transition require careful planning.