version unknown

migrate-to-vinext

cloudflare@cloudflare⭐ 9.4k stars· last commit 3d ago· 324 open issues

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).

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

8.0/10
Verified
Oct 11, 2026

// RATINGS

⭐GitHub Stars
⭐⭐⭐⭐⭐ 9.4k on GitHubGitHub ↗

Very popular

🟢ProSkills ScoreAI Verified
8.0/10
📍

Not yet listed on ClawHub or SkillsMP

// README

vinext

Run Next.js applications on Vite, with Cloudflare Workers as the primary deployment target.

Website: vinext.dev

Documentation: vinext.dev/docs

Read the announcement: How we rebuilt Next.js with AI in one week

Under active development. vinext supports substantial Next.js applications today, but it is not yet a drop-in replacement for every application or production workload. Expect compatibility gaps, especially in newer App Router features, and evaluate it against your own application before adopting it.

vinext reimplements the Next.js API surface on Vite rather than consuming next build output. It supports both the App Router and Pages Router, React Server Components, Server Actions, middleware, route handlers, ISR, static export, and the most commonly used next/* modules. Cloudflare Workers has the deepest integration; Node.js and other platforms are available with different levels of support.

Project status

What works today

  • App Router and Pages Router in development and production builds
  • React Server Components, Server Actions, route handlers, and middleware
  • Static generation, ISR, output: "export", and standalone Node.js output
  • Core Next.js APIs and modules, including next/link, next/image, next/navigation, next/headers, next/cache, and the Metadata API
  • Cloudflare Workers deployment with bindings, cache adapters, and image optimization support
  • Migration tooling through vinext check, vinext init, and the vinext Agent Skill

Known gaps we're working on

These are active compatibility areas, not permanent exclusions:

  • Cache Components and Partial Prerendering: "use cache" is partially implemented, but full cacheComponents behavior is still incomplete. Cache profiles, tags, partial shells, resume behavior, prefetching, and some dev/build cache semantics do not yet match Next.js in every case.
  • Build-time image and font optimization: images can be optimized at request time on Cloudflare, but vinext does not yet reproduce Next.js's complete build-time image pipeline. Google Fonts are loaded from the CDN, and local font CSS is injected at runtime rather than extracted during the build.
  • Native modules in App Router development: packages such as sharp, resvg, satori, lightningcss, and @napi-rs/canvas can fail in Vite's RSC development environment. Production builds support more of these cases than development mode.
  • Platform-specific and advanced Next.js behavior: preferredRegion route config is ignored, and runtime doesn't choose where a route runs (outside cacheComponents, a runtime = "edge" App Router page is never ISR-cached, as in Next.js), and some recently introduced or undocumented Next.js behavior may not yet be reproduced.

Run vinext check against an existing application before migrating. If a gap is not listed here, check the open issues or file a focused reproduction.

Quick start

Use the official setup commands below. They are the recommended way to create or migrate a vinext project because they configure dependencies, scripts, Vite, and your deployment target for you.

Start a new project with create-vinext-app:

pnpm create vinext-app@latest my-app

Migrate an existing Next.js project with vinext init:

npx vinext init

Optional: migrate with an AI agent

Prefer vinext init for a direct, repeatable migration. If you want an AI agent to investigate compatibility issues and guide the migration, vinext also includes an optional Agent Skill. It works with Claude Code, OpenCode, Cursor, Codex, and dozens of other AI coding tools:

npx skills add cloudflare/vinext

Then open your Next.js project in any supported tool and say:

migrate this project to vinext

The skill handles compatibility checking, dependency installation, config generation, and dev server startup. It knows what vinext supports and will flag anything that needs manual attention.

Or do it manually

npm install vinext
npm install -D vite @vitejs/plugin-react

If you're using the App Router, also install:

npm install react-server-dom-webpack
npm install -D @vitejs/plugin-rsc

Add a Vite config:

import { defineConfig } from "vite";
import vinext from "vinext";

export default defineConfig({
  plugins: [vinext()],
});

Then use Vite for development and builds:

{
  "scripts": {
    "dev": "vite dev",
    "build": "vite build",
    "start": "vinext start"
  }
}
npx vite dev        # Development server with HMR
npx vite build      # Production build
npx @vinext/cloudflare deploy  # Build and deploy to Cloudflare Workers

With Vite+, use vpx @vinext/cloudflare deploy, or vp exec vinext-cloudflare deploy when running the locally installed bin.

The vinext() plugin auto-detects your app/ or pages/ directory and loads next.config.js.

Your existing pages/, app/, next.config.js, and public/ directories work as-is. Run vinext check first to scan for known compatibility issues, or use vinext init to automate the full migration.

CLI reference

CommandDescription
vite devStart dev server with HMR
vite buildProduction build (multi-environment for App Router: RSC + SSR + client)
vinext startStart local production server for testing
npx @vinext/cloudflare deployBuild and deploy to Cloudflare Workers
vp exec vinext-cloudflare deployBuild and deploy to Cloudflare Workers with Vite+
vinext initMigrate a Next.js project to run under vinext
vinext checkScan your Next.js app for compatibility issues before migrating
vinext lintDelegate to eslint or oxlint

vinext dev and vinext build remain as thin aliases for the project-local Vite commands. They require a Vite config; if one is missing, run vinext init. Vite owns their options, output, and exit behavior. For older configured projects, the aliases still preload dotenv before Vite evaluates the config and add "type": "module" (renaming known CommonJS config files to .cjs) when an unambiguous default Vite config requires the ESM migration. An explicit "type": "commonjs" is never changed. Direct vite dev and vite build do not perform these wrapper compatibility steps.

@vinext/cloudflare deploy options: --preview, --env <name>, --name <name> (Wrangler config projects only), --vite-config <path>, --message <text>, --tag <text>, --skip-build, --dry-run, --warm-cache, --traffic-aware-warm-cache.

vinext init prompts for a deployment target, defaulting to Cloudflare. Agents must ask the user which target they want, then pass --platform=cloudflare or --platform=node. For Cloudflare, agents and CI must also pass --cdn-cache, --data-cache, and --image-optimization; see Run init without prompts.

Other options: --port <port> (default: 3001), --skip-check, --force.

Cloudflare init uses cf and cloudflare.config.ts by default. Both vinext init and create-vinext-app accept --legacy-wrangler-cloudflare-init to retain

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • .agents/skills/migrate-to-vinext/SKILL.md7.8 KBupstream ↗
    ---
    name: migrate-to-vinext
    description: 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).
    ---
    
    # Migrate Next.js to vinext
    
    vinext reimplements the Next.js API surface on Vite. Existing `app/`, `pages/`, and `next.config.js` work as-is — migration is a package swap, config generation, and ESM conversion. No changes to application code required.
    
    ## FIRST: Verify Next.js Project
    
    Confirm `next` is in `dependencies` or `devDependencies` in `package.json`. If not found, STOP — this skill does not apply.
    
    Detect the package manager from the lockfile:
    
    | Lockfile                    | Manager | Install       | Uninstall       |
    | --------------------------- | ------- | ------------- | --------------- |
    | `pnpm-lock.yaml`            | pnpm    | `pnpm add`    | `pnpm remove`   |
    | `yarn.lock`                 | yarn    | `yarn add`    | `yarn remove`   |
    | `bun.lockb` / `bun.lock`    | bun     | `bun add`     | `bun remove`    |
    | `package-lock.json` or none | npm     | `npm install` | `npm uninstall` |
    
    Detect the router: if an `app/` directory exists at root or under `src/`, it's App Router. If only `pages/` exists, it's Pages Router. Both can coexist.
    
    ## Quick Reference
    
    | Command                            | Purpose                                                                |
    | ---------------------------------- | ---------------------------------------------------------------------- |
    | `vinext check`                     | Scan project for compatibility issues, produce scored report           |
    | `vinext init`                      | Automated migration — installs deps, generates config, converts to ESM |
    | `vinext dev`                       | Development server with HMR                                            |
    | `vinext build`                     | Production build (multi-environment for App Router)                    |
    | `vinext start`                     | Local production server                                                |
    | `npx @vinext/cloudflare deploy`    | Build and deploy to Cloudflare Workers                                 |
    | `vp exec vinext-cloudflare deploy` | Build and deploy to Cloudflare Workers with Vite+                      |
    
    ## Phase 1: Check Compatibility
    
    Run `vinext check` (install vinext first if needed via `npx vinext check`). Review the scored report. If critical incompatibilities exist, inform the user before proceeding.
    
    See [references/compatibility.md](references/compatibility.md) for supported/unsupported features and ecosystem library status.
    
    ## Phase 2: Automated Migration (Recommended)
    
    Run `vinext init`. This command:
    
    1. Runs `vinext check` for a compatibility report
    2. Installs `vite` as a devDependency (and `@vitejs/plugin-rsc` for App Router)
    3. Adds `"type": "module"` to package.json
    4. Renames CJS config files (e.g., `postcss.config.js` → `.cjs`) to avoid ESM conflicts
    5. Adds `dev:vinext` and `build:vinext` scripts to package.json
    6. Generates a minimal `vite.config.ts`
    7. Adds `/dist/` and `.vinext/` to `.gitignore`
    
    This is non-destructive — the existing Next.js setup continues to work alongside vinext. Use the `dev:vinext` script to test before fully switching over.
    
    If `vinext init` succeeds, skip to Phase 4 (Verify). If it fails or the user prefers manual control, continue to Phase 3.
    
    ## Phase 3: Manual Migration
    
    Use this as a fallback when `vinext init` doesn't work or the user wants full control.
    
    ### 3a. Replace packages
    
    ```bash
    # Example with npm:
    npm uninstall next
    npm install vinext
    npm install -D vite
    # App Router only:
    npm install -D @vitejs/plugin-rsc
    ```
    
    ### 3b. Update scripts
    
    Replace all `next` commands in `package.json` scripts:
    
    | Before       | After          | Notes                      |
    | ------------ | -------------- | -------------------------- |
    | `next dev`   | `vinext dev`   | Dev server with HMR        |
    | `next build` | `vinext build` | Production build           |
    | `next start` | `vinext start` | Local production server    |
    | `next lint`  | `vinext lint`  | Delegates to eslint/oxlint |
    
    Preserve flags: `next dev --port 3001` → `vinext dev --port 3001`.
    
    ### 3c. Convert to ESM
    
    Add `"type": "module"` to package.json. Rename any CJS config files:
    
    - `postcss.config.js` → `postcss.config.cjs`
    - `tailwind.config.js` → `tailwind.config.cjs`
    - Any other `.js` config that uses `module.exports`
    
    ### 3d. Generate vite.config.ts
    
    See [references/config-examples.md](references/config-examples.md) for config variants per router and deployment target.
    
    If the project already has custom Vite config, prefer Vite 8-native keys when editing it: `oxc`, `optimizeDeps.rolldownOptions`, and `build.rolldownOptions`. Older `esbuild` and `build.rollupOptions` settings still work for now but are migration targets.
    
    **Pages Router (minimal):**
    
    ```ts
    import vinext from "vinext";
    import { defineConfig } from "vite";
    export default defineConfig({ plugins: [vinext()] });
    ```
    
    **App Router (minimal):**
    
    ```ts
    import vinext from "vinext";
    import { defineConfig } from "vite";
    export default defineConfig({ plugins: [vinext()] });
    ```
    
    vinext auto-registers `@vitejs/plugin-rsc` for App Router when the `rsc` option is not explicitly `false`. No manual RSC plugin config needed for local development.
    
    ### 3e. Update .gitignore
    
    Ensure vinext-generated output and caches are ignored:
    
    ```gitignore
    /dist/
    .vinext/
    ```
    
    ## Phase 4: Deployment (Optional)
    
    ### Option A: Cloudflare Workers (recommended for Cloudflare)
    
    If the user wants to deploy to Cloudflare Workers, use `npx @vinext/cloudflare deploy`. With Vite+, use `vp exec vinext-cloudflare deploy` when running the locally installed bin. It builds and deploys via wrangler.
    
    For manual setup or custom worker entries, see [references/config-examples.md](references/config-examples.md).
    
    #### Cloudflare Bindings (D1, R2, KV, AI, etc.)
    
    To access Cloudflare bindings (D1, R2, KV, AI, Queues, Durable Objects, etc.), use `import { env } from "cloudflare:workers"` in any server component, route handler, or server action:
    
    ```tsx
    import { env } from "cloudflare:workers";
    
    export default async function Page() {
      const result = await env.DB.prepare("SELECT * FROM posts").all();
      return <div>{JSON.stringify(result)}</div>;
    }
    ```
    
    This works because `@cloudflare/vite-plugin` runs server environments in workerd, where `cloudflare:workers` is a native module. No custom worker entry, no `getPlatformProxy()`, no special configuration needed. Just import and use.
    
    Bindings must be defined in `wrangler.jsonc`. For TypeScript types, run `wrangler types`.
    
    **IMPORTANT:** Do not use `getPlatformProxy()`, `getRequestContext()`, or custom worker entries with `fetch(request, env)` to access bindings. These are older patterns. `cloudflare:workers` is the recommended approach and works out of the box with vinext.
    
    ### Option B: Other platforms (via Nitro)
    
    For deploying to Vercel, Netlify, AWS, Deno Deploy, or any other [Nitro-supported platform](https://v3.nitro.build/deploy), add the Nitro Vite plugin:
    
    ```bash
    npm install nitro
    ```
    
    ```ts
    // vite.config.ts
    import { defineConfig } from "vite";
    import vinext from "vinext";
    import { nitro } from "nitro/vite";
    
    export default defineConfig({
      plugins: [vinext(), nitro()],
    });
    ```
    
    Build and deploy:
    
    ```bash
    NITRO_PRESET=vercel npx vite build    # Vercel
    NITRO_PRESET=netlify npx vite build   # Netlify
    NITRO_PRESET=deno_deploy npx vite build  # Deno Deploy
    NITRO_PRESET=node npx vite build      # Node.js server
    ```
    
    Nitro auto-detects the platform in most CI/CD environments, so the preset is often unnecessary.
    
    **Note:** For Cloudflare Workers, Nitro works but the native integration (`npx @vinext/cloudflare deploy` / `vp exec vinext-cloudflare deploy` / `@cloud
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/cloudflare-vinext-agents-skills-migrate-to-vinext.md

// REPO STATS

9.4k stars
324 open issues
Last commit: 3d ago