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
npx skills add secondsky/claude-skills --skill cloudflare-workers-migration -a claude-codeWhat 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 definederror when deploying to edge - replace
process.envwith theenvparameter in handlers - check Node.js API compatibility before migration
Example prompts for the agent
- Port the Lambda handler from
handler.jsto Workers, name the fileworker.ts - Adapt Express middleware from
app.jsto Hono, save it assrc/index.ts - Check which Node.js APIs in
package.jsonare unsupported in Workers
How to install cloudflare-workers-migration
1Skills CLI (Vercel)
npx skills add secondsky/claude-skills --skill cloudflare-workers-migration -a claude-code2Manually: put the files in place
~/.claude/skills/cloudflare-workers-migration/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/cloudflare-workers-migration/
1Skills CLI (Vercel)
npx skills add secondsky/claude-skills --skill cloudflare-workers-migration -a codex2Manually: put the files in place
.agents/skills/cloudflare-workers-migration/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add secondsky/claude-skills --skill cloudflare-workers-migration -a cursor2Manually: put the files in place
.cursor/skills/cloudflare-workers-migration/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install secondsky/claude-skills plugins/cloudflare-workers/skills/cloudflare-workers-migration2Manually: put the files in place
.github/skills/cloudflare-workers-migration/SKILL.md1Skills CLI (Vercel)
npx skills add secondsky/claude-skills --skill cloudflare-workers-migration -a gemini-cli2Platform CLI
gemini skills install https://github.com/secondsky/claude-skills --path plugins/cloudflare-workers/skills/cloudflare-workers-migrationManually: put the files in place
.devin/skills/cloudflare-workers-migration/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add secondsky/claude-skills --skill cloudflare-workers-migration -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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