cloudflare-workers-migration

Workers Migration Guide

Migrate existing applications to Cloudflare Workers from various platforms.

Migration Decision Tree

What are you migrating from?
├── AWS Lambda
│   └── Node.js handler? → Lambda adapter pattern
│   └── Python? → Consider Python Workers
│   └── Container/custom runtime? → May need rewrite
├── Vercel/Next.js
│   └── API routes? → Minimal changes with adapter
│   └── Full Next.js app? → Use OpenNext adapter
│   └── Middleware? → Direct Workers equivalent
├── Express/Node.js
│   └── Simple API? → Hono (similar API)
│   └── Complex middleware? → Gradual migration
│   └── Heavy node: usage? → Compatibility layer
└── Other Edge (Deno Deploy, Fastly)
    └── Standard Web APIs? → Minimal changes
    └── Platform-specific? → Targeted rewrites

Platform Comparison

Feature	Workers	Lambda	Vercel	Express
Cold Start	~0ms	100-500ms	10-100ms	N/A
CPU Limit	50ms/10ms	15 min	10s	None
Memory	128MB	10GB	1GB	System
Max Response	6MB (stream unlimited)	6MB	4.5MB	None
Global Edge	300+ PoPs	Regional	~20 PoPs	Manual
Node.js APIs	Partial	Full	Full	Full

Top 10 Migration Errors

Error	From	Cause	Solution
fs is not defined	Lambda/Express	File system access	Use KV/R2 for storage
Buffer is not defined	Node.js	Node.js globals	Import from node:buffer
process.env undefined	All	Env access pattern	Use env parameter
setTimeout not returning	Lambda	Async patterns	Use ctx.waitUntil()
require() not found	Express	CommonJS	Convert to ESM imports
Exceeded CPU time	All	Long computation	Chunk or use DO
body already consumed	Express	Request body	Clone before read
Headers not iterable	Lambda	Headers API	Use Headers constructor
crypto.randomBytes	Node.js	Node crypto	Use crypto.getRandomValues
Cannot find module	All	Missing polyfill	Check Workers compatibility

Quick Migration Patterns

AWS Lambda Handler

// Before: AWS Lambda
export const handler = async (event, context) => {
  const body = JSON.parse(event.body);
  return {
    statusCode: 200,
    body: JSON.stringify({ message: 'Hello' }),
  };
};

// After: Cloudflare Workers
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const body = await request.json();
    return Response.json({ message: 'Hello' });
  },
};

Express Middleware

// Before: Express
app.use((req, res, next) => {
  if (!req.headers.authorization) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  next();
});

// After: Hono Middleware
app.use('*', async (c, next) => {
  if (!c.req.header('Authorization')) {
    return c.json({ error: 'Unauthorized' }, 401);
  }
  await next();
});

Environment Variables

// Before: Node.js
const apiKey = process.env.API_KEY;

// After: Workers
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const apiKey = env.API_KEY;
    // ...
  },
};

Node.js Compatibility

Workers support many Node.js APIs via compatibility flags:

// wrangler.jsonc
{
  "compatibility_flags": ["nodejs_compat_v2"],
  "compatibility_date": "2024-12-01"
}

Supported with nodejs_compat_v2:

• crypto (most methods)
• buffer (Buffer class)
• util (promisify, types)
• stream (Readable, Writable)
• events (EventEmitter)
• path (all methods)
• string_decoder
• assert

Not Supported (need alternatives):

• fs → Use R2/KV
• child_process → Not possible
• cluster → Not applicable
• dgram → Not supported
• net → Use fetch/WebSocket
• tls → Handled by platform

When to Load References

Reference	Load When
references/lambda-migration.md	Migrating AWS Lambda functions
references/vercel-migration.md	Migrating from Vercel/Next.js
references/express-migration.md	Migrating Express/Node.js apps
references/node-compatibility.md	Node.js API compatibility issues

Migration Checklist

1. Analyze Dependencies: Check for unsupported Node.js APIs
2. Convert to ESM: Replace require() with import
3. Update Env Access: Use env parameter instead of process.env
4. Replace File System: Use R2/KV for storage
5. Handle Async: Use ctx.waitUntil() for background tasks
6. Test Locally: Verify with wrangler dev
7. Performance Test: Ensure CPU limits aren't exceeded

See Also

• workers-runtime-apis - Available APIs in Workers
• workers-performance - Optimization techniques
• cloudflare-worker-base - Basic Workers setup