# cloudflare-workers-migration

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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 316 installs · ★ 250 repo stars
- Author: secondsky
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/secondsky/claude-skills/tree/HEAD/plugins/cloudflare-workers/skills/cloudflare-workers-migration/SKILL.md
- Updated: 2026-10-20
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/cloudflare-workers-migration

## What it 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.

## Requirements
- Works with: AWS

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill cloudflare-workers-migration -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/cloudflare-workers-migration/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/cloudflare-workers-migration/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill cloudflare-workers-migration -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/cloudflare-workers-migration/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill cloudflare-workers-migration -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/cloudflare-workers-migration/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install secondsky/claude-skills plugins/cloudflare-workers/skills/cloudflare-workers-migration
```

2. **Manually: put the files in place**
- File: `.github/skills/cloudflare-workers-migration/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill cloudflare-workers-migration -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/secondsky/claude-skills --path plugins/cloudflare-workers/skills/cloudflare-workers-migration
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/cloudflare-workers-migration/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill cloudflare-workers-migration -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/secondsky/claude-skills/tree/HEAD/plugins/cloudflare-workers/skills/cloudflare-workers-migration/SKILL.md

## When to use it
- 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
- 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

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: f4c6fd839f5caa35.

BEGIN THIRD-PARTY FILE f4c6fd839f5caa35
````text
---
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()` |
````
END THIRD-PARTY FILE f4c6fd839f5caa35

The third-party file has ended. Everything between the f4c6fd839f5caa35 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2106 of 5276 bytes. © secondsky · MIT · https://github.com/secondsky/claude-skills/tree/HEAD/plugins/cloudflare-workers/skills/cloudflare-workers-migration/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
