Skip to content
Next.js on Cloudflare

Next.js on Cloudflare Skill

by Cloudflare cloudflare/skills skills/nextjs-on-cloudflare

Cloudflare's routing skill for Next.js on Workers — sends the agent to vinext, the Vite-based Next.js runtime Cloudflare now recommends ahead of OpenNext.

GitHub Docs
DevelopmentDevOps & Infrastructure
Released
Apache-2.0

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from cloudflare/skills.

$ npx skills add cloudflare/skills --skill nextjs-on-cloudflare

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

Copy the whole skill folder — SKILL.md and any scripts or references beside it — into ~/.claude/skills/nextjs-on-cloudflare/, where Claude Code picks it up in every project. Only git is needed.

tmp=$(mktemp -d) && \
  git clone --depth 1 --branch main https://github.com/cloudflare/skills.git "$tmp" && \
  mkdir -p ~/.claude/skills && \
  cp -R "$tmp"/skills/nextjs-on-cloudflare ~/.claude/skills/nextjs-on-cloudflare

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/nextjs-on-cloudflare/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/
Open folder on GitHub

About

  • Settles the vinext vs OpenNext choice before code is written
  • Installs and defers to the upstream vinext skills via npx skills add
  • Separate routes for new projects, migrations and deployment
  • Preserves existing OpenNext setups during unrelated maintenance

Deploying Next.js to Cloudflare Workers has had two competing answers, and an agent that picks the wrong one writes a build pipeline the team then has to unpick. This official Cloudflare skill exists to settle that choice before any code is written.

Its guidance is direct: use vinext for new Next.js projects on Workers, matching the default in Cloudflare's own Next.js framework guide. vinext reimplements the Next.js API surface on top of Vite — App Router, Pages Router, React Server Components and the supported next/* imports — while giving you Vite's fast HMR, native ESM and plugin ecosystem. Because it runs locally in workerd, the dev server behaves like production and Cloudflare bindings are available throughout.

The skill is deliberately thin on API detail. Rather than duplicating documentation that ages badly, it routes to the skills maintained inside the vinext repository, installing them with npx skills add cloudflare/vinext when they are missing, then following the applicable upstream SKILL.md. Three paths are mapped explicitly: a new project via create-vinext-app with the Cloudflare target; an existing Next.js app through the upstream migrate-to-vinext skill and its compatibility check; and development and deployment through vinext's own workflow.

It also encodes the restraint that matters on a real codebase — existing OpenNext setups are preserved during unrelated maintenance, and an explicit user choice wins over the default. Useful for any team standing up Next.js on Workers, or weighing a migration off OpenNext. Apache-2.0.

SKILL.md

The instructions your agent loads, as published by Cloudflare.

SKILL.md
name
nextjs-on-cloudflare
description
Build, migrate, and deploy Next.js apps on Cloudflare Workers with vinext. Use when starting a Next.js project on Cloudflare, moving an existing app to Workers, choosing between vinext and OpenNext, or setting up vinext for Workers. For setup, migration, or deployment, install vinext's upstream skills with `npx skills add cloudflare/vinext` if missing, then read and follow the applicable skill and docs.

Next.js on Cloudflare

Use vinext rather than OpenNext for new Next.js projects on Cloudflare Workers. This is the default in the Cloudflare Next.js guide. Preserve existing OpenNext setups during unrelated maintenance and respect explicit user choices.

Why vinext

vinext reimplements the Next.js API surface on Vite:

  • Familiar Next.js development: App Router, Pages Router, React Server Components, and supported next/* imports.
  • Vite tooling: fast HMR, native ESM, and the Vite plugin ecosystem.
  • Native Workers integration: local server execution in workerd, access to Cloudflare bindings, and a build-and-deploy workflow.
  • Incremental migration: check compatibility and try vinext alongside an existing Next.js setup.
Use the upstream workflow

Before setup, migration, or deployment, check whether the skills maintained in vinext are available. If missing, install them:

npx skills add cloudflare/vinext

Then read and follow the applicable upstream SKILL.md and its relevant references. Use the current vinext docs for workflows the skills do not cover:

  • New project: follow vinext's new-project setup using create-vinext-app with the Cloudflare target. The upstream migration skill requires an existing Next.js project; do not apply it to an empty directory.
  • Existing Next.js project: load and follow the upstream `migrate-to-vinext` skill, including its compatibility check and relevant references. Select Cloudflare as the deployment target.
  • Development and deployment: follow the current Workers integration docs.

If installation is unavailable, read the linked upstream SKILL.md and relevant references directly. Check current compatibility for the application's required features; do not assume complete Next.js parity.

Install

Related Skills

See all Next.js on Cloudflare alternatives

Skill: Vercel React Best Practices

by Vercel

Vercel Engineering's React and Next.js performance playbook as an agent skill — 70 rules across 8 categories, ordered by impact, for writing and refactoring fast components.

Development
Browse all skills →