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 rewritesPlatform 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_decoderassert
Not Supported (need alternatives):
fs→ Use R2/KVchild_process→ Not possiblecluster→ Not applicabledgram→ Not supportednet→ Use fetch/WebSockettls→ 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
- Analyze Dependencies: Check for unsupported Node.js APIs
- Convert to ESM: Replace require() with import
- Update Env Access: Use env parameter instead of process.env
- Replace File System: Use R2/KV for storage
- Handle Async: Use ctx.waitUntil() for background tasks
- Test Locally: Verify with wrangler dev
- Performance Test: Ensure CPU limits aren't exceeded
See Also
workers-runtime-apis- Available APIs in Workersworkers-performance- Optimization techniquescloudflare-worker-base- Basic Workers setup