Deploy Next.js to Cloudflare Workers via OpenNext adapter. Use for SSR, ISR, App/Pages Router, or encountering worker size limits, runtime compatibility, connection scoping errors.
Installs just this skill. Get the whole plugin for auto-invocation.
⚡ How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/cloudflare-nextjs
👁️ Context preview
The summary Claude sees to decide when to auto-load this skill.
Deploy Next.js to Cloudflare Workers via OpenNext adapter. Use for SSR, ISR, App/Pages Router, or encountering worker size limits, runtime compatibility, connection scoping errors.
Deploy Next.js applications to Cloudflare Workers using the OpenNext Cloudflare adapter for production-ready serverless Next.js hosting.
## When to Load References
Load additional reference files based on your specific task:
- **`references/error-catalog-extended.md`** - Load when encountering ANY error during setup, build, or deployment. Contains complete catalog of 11+ documented issues with root causes, solutions, and official sources.
- **`references/service-integration-patterns.md`** - Load when integrating Cloudflare services (D1, R2, KV, Workers AI) with Next.js. Contains complete patterns for database queries, file uploads, caching, and AI inference.
- **`references/troubleshooting.md`** - Load for general troubleshooting and debugging guidance beyond the error catalog.
- **`references/feature-support.md`** - Load when checking if a specific Next.js feature is supported on Cloudflare Workers (e.g., "Can I use Server Actions?", "Does ISR work?").
- **`references/database-client-example.ts`** - Load when integrating external database clients (Drizzle, Prisma, PostgreSQL, MySQL) with proper request-scoping patterns required by Workers.
- **`references/open-next.config.ts`** - Load when configuring caching behavior, image optimization, or custom OpenNext settings.
- **`references/package.json`** - Load when setting up a new project or migrating an existing Next.js application to Cloudflare Workers.
- **`references/wrangler.jsonc`** - Load when configuring Worker settings, compatibility flags, environment bindings (D1, R2, KV, AI), or deployment options.
## Use This Skill When
- Deploying Next.js applications (App Router or Pages Router) to Cloudflare Workers
- Need server-side rendering (SSR), static site generation (SSG), or incremental static regeneration (ISR) on Cloudflare
- Migrating existing Next.js apps from Vercel, AWS, or other platforms to Cloudflare
- Building full-stack Next.js applications with Cloudflare services (D1, R2, KV, Workers AI)
- Need React Server Components, Server Actions, or Next.js middleware on Workers
- Want global edge deployment with Cloudflare's network
## Key Differences from Standard Next.js
**OpenNext Adapter** transforms Next.js builds for Workers. **Critical requirements**:
- Node.js runtime (NOT Edge) via `nodejs_compat` flag
1. Runs Next.js official setup tool (`create-next-app`)
2. Installs `@opennextjs/cloudflare` adapter
3. Creates `wrangler.jsonc` with correct configuration
4. Creates `open-next.config.ts` for caching configuration
5. Adds deployment scripts to `package.json`
6. Optionally deploys immediately to Cloudflare
**Development workflow**:
```bash
npm run dev # Next.js dev server (fast reloads)
npm run preview # Test in workerd runtime (production-like)
npm run deploy # Build and deploy to Cloudflare
```
### Existing Project Migration
To add the OpenNext adapter to an existing Next.js application:
#### 1. Install the adapter
```bash
bun add -d @opennextjs/cloudflare
```
##### Secure Installation
Adapter packages handle production traffic — pin exact versions and audit before upgrading. Follow supply chain security best practices:
- **Block post-install scripts** — `npm config set ignore-scripts true` (or Bun: disabled by default)
- **Cooldown period** — Wait 7 days for new package versions to be vetted by the community
- **Audit before installing** — Run `socket package score npm <pkg>` or use `socket npm install <pkg>` to check packages
Load the `dependency-upgrade` skill for full security configuration including Socket CLI integration, cooldown setup, lockfile validation, and CI enforcement.
- `dev`: Next.js development server (fast iteration)
- `preview`: Build + run in workerd runtime (test before deploy)
- `deploy`: Build + deploy to Cloudflare
- `cf-typegen`: Generate TypeScript types for Cloudflare bindings
#### 5. Ensure Node.js runtime (not Edge)
Remove Edge runtime exports from your app:
```typescript
// ❌ REMOVE THIS (Edge runtime not supported)
export const runtime = "edge";
// ✅ Use Node.js runtime (default)
// No export needed - Node.js is default
```
## Development Workflow
**Dual Testing Required**:
- `npm run dev` - Fast iteration (Next.js dev server)
- `npm run preview` - Production-like testing (workerd runtime, **REQUIRED before deploy**)
- `npm run deploy` - Build and deploy
**Critical**: Always test `preview` before deploying to catch Workers-specific runtime issues
## Critical Configuration
**wrangler.jsonc** minimum requirements:
```jsonc
{
"compatibility_date": "2025-05-05", // Minimum for FinalizationRegistry
"compatibility_flags": ["nodejs_compat"] // Required for Node.js runtime
}
```
**Cloudflare Bindings**: Add D1, R2, KV, or AI bindings in `wrangler.jsonc`, access via `process.env` (see "Cloudflare Services Integration" section for complete patterns)
**Package Exports** (if needed): Create `.env` with `WRANGLER_BUILD_PLATFORM="node"` to prioritize Node.js exports
## Top 5 Critical Errors
These are the most common deployment-blocking errors. **For the complete catalog of 11+ errors, load `references/error-catalog-extended.md`**.
### 1. Worker Size Limit Exceeded
**Error**: `"Your Worker exceeded the size limit of 3 MiB"` (Free) or `"10 MiB"` (Paid)
**Quick Fix**: Upgrade plan, analyze bundle with `bunx opennextjs-cloudflare build` → check `.open-next/server-functions/default/handler.mjs.meta.json`, remove unused dependencies, or use dynamic imports.
**More Errors**: Load `references/error-catalog-extended.md` for 6 additional documented errors including FinalizationRegistry issues, Durable Objects warnings, Prisma conflicts, cross-fetch errors, and Windows development issues
## Feature Support Matrix
| Feature | Status | Notes |
|---------|--------|-------|
| **App Router** | ✅ Fully Supported | Latest App Router features work |
- R2: Upload, download, list, delete with streaming
- KV: Get, set with TTL, delete, list keys
- Workers AI: Text generation, embeddings, image classification
- Multi-service integration examples
- TypeScript types for bindings (`npm run cf-typegen`)
**Related Skills**: `cloudflare-d1`, `cloudflare-r2`, `cloudflare-kv`, `cloudflare-workers-ai` for service-specific deep dives
## Image Optimization & Caching
**Images**: Automatic optimization via Cloudflare Images (billed separately). Configure in `open-next.config.ts` with `imageOptimization: { loader: 'cloudflare' }`. Use standard Next.js `<Image />` component.
**Caching**: OpenNext provides sensible defaults. Override in `open-next.config.ts` if needed. See https://opennext.js.org/cloudflare/caching for advanced configuration
## Known Limitations
### Not Yet Supported
1. **Node.js Middleware (Next.js 15.2+)**
- Introduced in Next.js 15.2
- Support planned for future releases
- Use standard middleware for now
2. **Edge Runtime**
- Only Node.js runtime supported
- Remove `export const runtime = "edge"` from your app
3. **Full Windows Support**
- Development on Windows not fully guaranteed
- Use WSL, VM, or Linux-based CI/CD
### Worker Size Constraints
- **Free plan**: 3 MiB limit (gzip-compressed)
- **Paid plan**: 10 MiB limit (gzip-compressed)
- Monitor bundle size during development
- Use dynamic imports for code splitting
### Database Connections
- External database clients (PostgreSQL, MySQL) must be request-scoped
- Cannot reuse connections across requests (Workers limitation)
- Prefer Cloudflare D1 for database needs (designed for Workers)
## Deployment
**Local**: `npm run deploy` (builds and deploys)
**CI/CD**: Use `npm run deploy` command in GitHub Actions, GitLab CI, or Cloudflare Workers Builds (auto-detected)
**Custom Domains**: Workers & Pages → Settings → Domains & Routes (domain must be on Cloudflare)
## TypeScript & Testing
**TypeScript Types**: Run `npm run cf-typegen` to generate `cloudflare-env.d.ts` with typed bindings (D1Database, R2Bucket, KVNamespace, Ai)
**Testing**: Always test in `preview` mode before deployment to catch Workers-specific runtime issues and verify bindings work correctly
## Migration from Other Platforms
### From Vercel
1. Copy existing Next.js project
2. Run existing project migration steps (above)
3. Update environment variables in Cloudflare dashboard
4. Replace Vercel-specific features:
- Vercel Postgres → Cloudflare D1
- Vercel Blob → Cloudflare R2
- Vercel KV → Cloudflare KV
- Vercel Edge Config → Cloudflare KV
5. Test thoroughly with `npm run preview`
6. Deploy with `npm run deploy`
### From AWS / Other Platforms
Same process as Vercel migration - the adapter handles Next.js standard features automatically.
