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

• 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 Workers

• workers-performance

• Optimization techniques

• cloudflare-worker-base

• Basic Workers setup