Skip to main content
skill CX Codex

cloudflare-workers-migration — Claude Code skill: migrate to edge

cloudflare-workers-migration — a skill for porting applications to Cloudflare Workers from AWS Lambda, Vercel, Express and Node.js. Adapts handlers, middleware and environment variables to Web APIs.

MIT 316 installs ★ 250 updated 2026-10-20

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add secondsky/claude-skills --skill cloudflare-workers-migration -a claude-code
Open on GitHub

What cloudflare-workers-migration does

Includes a decision tree for choosing a migration strategy: Lambda adapters, Hono for Express, OpenNext for Next.js apps. Contains a Node.js API compatibility table showing what is available via the nodejs_compat_v2 flag in wrangler.jsonc and what needs alternatives (fs → R2/KV, child_process is not supported). Ten common errors (fs is not defined, Buffer is not defined, Exceeded CPU time) come with causes and fixes.

Provides examples of rewriting Lambda handlers to fetch, Express middleware to Hono, and replacing process.env with the env parameter. The CPU limit is 50 ms per request: long computations must be chunked or moved to Durable Objects. Background tasks use ctx.waitUntil() instead of setTimeout.

The migration checklist covers dependency analysis, CommonJS to ESM conversion, file system replacement with storage services, and testing with wrangler dev. The skill loads reference guides for Lambda, Vercel, Express migrations and Node.js API compatibility based on the task at hand.

What it helps with

  • port a Lambda function to Cloudflare Workers
  • adapt Express middleware to Workers Runtime
  • fix fs is not defined error when deploying to edge
  • replace process.env with the env parameter in handlers
  • check Node.js API compatibility before migration

Example prompts for the agent

  • Port the Lambda handler from handler.js to Workers, name the file worker.ts
  • Adapt Express middleware from app.js to Hono, save it as src/index.ts
  • Check which Node.js APIs in package.json are unsupported in Workers

How to install cloudflare-workers-migration

1Skills CLI (Vercel)

npx skills add secondsky/claude-skills --skill cloudflare-workers-migration -a claude-code

2Manually: put the files in place

~/.claude/skills/cloudflare-workers-migration/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/cloudflare-workers-migration/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about cloudflare-workers-migration

How to install cloudflare-workers-migration in Claude Code?

Run npx skills add secondsky/claude-skills --skill cloudflare-workers-migration -a claude-code, the skill will be installed to ~/.claude/skills/cloudflare-workers-migration/SKILL.md.

What does cloudflare-workers-migration do?

Ports server applications to Cloudflare Workers. Gives adaptation patterns for Lambda handlers, Express middleware and environment variables to Web APIs, a Node.js API compatibility table, and solutions for ten common migration errors.

Which Node.js APIs do not work in Workers?

fs, child_process, cluster, and dgram are not supported. Use R2 or KV for files, fetch or WebSocket for network requests. Modules like crypto, buffer, stream, and path are available via the nodejs_compat_v2 flag.

Source text

SKILL.md · MIT
---
name: cloudflare-workers-migration
description: Migrate to Cloudflare Workers from AWS Lambda, Vercel, Express, and Node.js. Use when porting existing applications to the edge, adapting serverless functions, or resolving Node.js API compatibility issues.
metadata:
  version: "1.0.0"
license: MIT
---

# 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

```typescript
// 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

```typescript
// 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

```typescript
// 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:

```jsonc
// 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

© secondsky · MIT · secondsky/claude-skills

Similar skills

All skills for Backend and APIs →

From the same set138

The whole set →
cloudflare-workers-observability A skill for Cloudflare Workers observability: structured logging, Analytics Engine, Tail Workers, metrics and alerting. Useful when a worker fails in production and you can't see why. CX Codex +1 322installs xss-prevention The xss-prevention skill helps prevent XSS with input sanitization, output encoding, and CSP. Use it for user HTML, comments, rich text, and script injection issues. CX Codex +1 320installs cloudflare-workers-multi-lang cloudflare-workers-multi-lang guides Cloudflare Workers development in Rust, Python, and WebAssembly. Useful when offloading heavy computation to WASM modules. CX Codex +1 317installs cloudflare-r2 Skill for working with Cloudflare R2, an S3-compatible object storage. Manages buckets, uploads, CORS and presigned URLs — everything needed to handle files in the cloud. CX Codex +1 316installs tanstack-query This skill guides Claude Code through TanStack Query v5 for fetching, caching, mutations, and v4 migration issues in React projects. CX Codex +1 314installs zustand-state-management zustand-state-management guides agent setup of Zustand v5 stores for React 18+ and TypeScript 5+. Fixes Next.js hydration mismatches and prevents selector re-render loops. CX Codex +1 301installs nextjs Skill for Next.js 16 and React 19.2 with App Router, Server Components, Server Actions, and caching patterns. Handles migration from version 15, async params errors, and Partial Prerendering setup. CX Codex +1 299installs feature-dev The feature-dev skill guides feature work through seven phases, from codebase discovery to review. Use it for multi-file changes and unclear architecture decisions. CX Codex +1 294installs

Project sponsors

Companies that keep this analytics open