skilld
All skills
cloudflare avatar

/migrate-to-vinext

@115771d
by cloudflarecloudflare/vinext9.1k stars
427

Migrates Next.js projects to vinext (Vite-based Next.js reimplementation). Load when asked to migrate, convert, or switch from Next.js to vinext. Handles compatibility scanning, package replacement, Vite config generation, ESM conversion, and deployment setup (Cloudflare Workers natively, other platforms via Nitro).

Ask your Agent

Use this Skill: https://skilld.dev/gh/cloudflare/vinext/migrate-to-vinext

This session only. Nothing lands on disk.

referencescompatibility.md

≈1.7k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Compatibility Reference

Supported next/* Imports

All of these resolve automatically to vinext shims. Do not rewrite imports in application code.

Import Status Notes
next/link Full
next/image Partial Remote images via @unpic; no build-time optimization
next/head Full
next/router Full Pages Router
next/navigation Full App Router
next/server Full NextRequest, NextResponse, cookies, userAgent, after, connection
next/headers Full
next/dynamic Full
next/script Full
next/font/google Partial CDN-loaded, not self-hosted
next/font/local Partial Runtime injection
next/og Full Via @vercel/og
next/cache Full Pluggable CacheHandler
next/form Full
next/legacy/image Full
next/error Full
next/config Full
next/document Full Pages Router
next/constants Full
next/amp Stub No-op; AMP deprecated since Next.js 13
next/web-vitals Stub No-op
server-only Full
client-only Full

Routing Features

Feature Supported
Pages Router (pages/) Yes
App Router (app/) Yes
Dynamic routes [param] Yes
Catch-all [...slug] Yes
Optional catch-all [[...slug]] Yes
Route groups (group) Yes
Parallel routes @slot Yes
Intercepting routes (.), (..), (...) Yes
Route handlers (route.ts) Yes
Middleware / proxy.ts (Next.js 16) Yes
i18n (path prefix) Yes
i18n (domain-based) No
basePath Yes
trailingSlash Yes

Server Features

Feature Supported
SSR (streaming) Yes
React Server Components Yes
Server Actions ("use server") Yes
getStaticProps / getStaticPaths Yes
getServerSideProps Yes
ISR (stale-while-revalidate) Yes
"use cache" / cacheLife() / cacheTag() Yes
Metadata API (metadata, generateMetadata) Yes
generateStaticParams Yes
Static export (output: 'export') Yes
instrumentation.ts Yes
connection() Yes
Pluggable CacheHandler Yes
PPR (Partial Prerendering) No — use "use cache"

Route Segment Config

Config Supported
revalidate Yes
dynamic Yes
dynamicParams Yes
runtime Partly: edge App Router pages skip ISR outside cacheComponents; placement is ignored
preferredRegion Ignored

next.config.js Options

vinext loads and respects: redirects, rewrites, headers, basePath, trailingSlash, i18n (path prefix), images, env, NEXT_PUBLIC_* env vars, output, serverExternalPackages (consider using Vite's ssr.external instead).

Ignored: webpack, turbopack, experimental.turbo.

Ecosystem Libraries

Tested and working:

  • next-themes
  • nuqs
  • next-view-transitions
  • next-intl
  • better-auth
  • @vercel/analytics
  • tailwindcss
  • framer-motion
  • shadcn-ui
  • lucide-react
  • drizzle
  • prisma

Not Supported

These features are intentionally excluded:

  • Vercel-specific bindings (@vercel/og edge runtime, Vercel Analytics server bindings)
  • AMP (deprecated since Next.js 13)
  • next export (legacy — use output: 'export')
  • Turbopack/webpack configuration
  • next/jest (use Vitest)
  • create-next-app scaffolding
  • Bug-for-bug parity with undocumented Next.js behavior
  • Native Node modules in Workers (sharp, resvg, satori — auto-stubbed in production)

Source: SKILL.md on GitHub

Third-party checks

No alerts3d5 checks · Risk SAFE
  • Gen Agent Trust Hub3d

    This skill provides a guided process for migrating web projects to a new build system and framework. It utilizes standard developer workflows, including automated package management and command execution for building and deploying applications. These operations are appropriate for the skill's stated purpose of project migration.

  • Socket3d

    No alerts

  • Snyk3d

    Risk: LOW · No issues

  • Runlayer6mo

    4 files scanned · No issues

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 115771d. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 hours ago.

Activeupdated 3 days ago

Topics

  • Next.js
  • vite
  • vinext
  • migration
  • cloudflare
  • workers
  • esm
  • app-router
  • pages-router
  • nitro

README badge

README badge for cloudflare/vinext

What it does

Migrates Next.js projects to vinext, a Vite-based reimplementation of Next.js that runs existing app/ and pages/ directories without code changes. Handles compatibility scanning, package replacement, Vite config generation, ESM conversion, and deployment to Cloudflare Workers or other platforms via Nitro.

Generated from the current SKILL.md.

Frequently asked

Do I need to rewrite my app/ or pages/ directory?
No. vinext reimplements the Next.js API surface on Vite, so existing `app/`, `pages/`, and `next.config.js` work as-is without code changes.
What package managers does this support?
The skill detects and works with npm, pnpm, yarn, and bun based on the lockfile present in the project.
Can I deploy to platforms other than Cloudflare?
Yes. For Vercel, Netlify, AWS, Deno Deploy, and other platforms, add the Nitro Vite plugin and set the appropriate NITRO_PRESET during build. For Cloudflare Workers specifically, the native `vinext deploy` integration is recommended.
How do I access Cloudflare bindings like D1, R2, or KV?
Use `import { env } from "cloudflare:workers"` in server components or route handlers. Bindings must be defined in `wrangler.jsonc`, and this approach works out of the box with vinext and `@cloudflare/vite-plugin`.
What happens if vinext init fails?
The skill provides a manual migration path (Phase 3) that covers package replacement, script updates, ESM conversion, and Vite config generation as a fallback.

Generated from the current SKILL.md. These answers refresh after source changes.