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

Top 10 Migration Errors

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

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