Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cloudflare/vinext/llms.txt

Use this file to discover all available pages before exploring further.

​
Quick Start

Get up and running with vinext in just a few minutes. This guide will walk you through the fastest path to a working vinext application.
vinext is a drop-in replacement for the Next.js CLI. If you have an existing Next.js project, you can migrate it to vinext with minimal changes.
The easiest way to get started is using the Agent Skill that handles migration automatically. It works with Claude Code, OpenCode, Cursor, Codex, and dozens of other AI coding tools.
1

Install the Agent Skill

Run this command in your terminal:
npx skills add cloudflare/vinext
2

Open Your Next.js Project

Open your Next.js project in any supported AI coding tool (Claude Code, OpenCode, Cursor, etc.)
3

Run the Migration

Ask the AI:
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.

​
Option 2: One-Command Migration

If you prefer to migrate manually, vinext provides a single command that automates the entire process.
1

Install vinext

In your existing Next.js project, install vinext:
npm install vinext
2

Run vinext init

Run the migration command:
npx vinext init
This will:
  • Run compatibility check to scan for issues
  • Install vite and @vitejs/plugin-rsc (for App Router)
  • Rename CJS config files to avoid ESM conflicts
  • Add "type": "module" to package.json
  • Add dev:vinext and build:vinext scripts
  • Generate a minimal vite.config.ts
The migration is non-destructive. Your existing Next.js setup continues to work alongside vinext.
3

Start the Development Server

Start the vinext dev server:
npm run dev:vinext
Your app will be available at http://localhost:3001 (port 3001 to avoid conflicts with Next.js).Your original Next.js setup still works:
npm run dev  # Still runs Next.js

​
Option 3: Manual Setup

For maximum control, you can set up vinext manually in just a few steps.
1

Install vinext

npm install vinext
2

Update package.json Scripts

Replace next with vinext in your scripts:
package.json
{
  "scripts": {
    "dev": "vinext dev",
    "build": "vinext build",
    "start": "vinext start"
  }
}
3

Start the Dev Server

npm run dev
vinext auto-detects your app/ or pages/ directory, loads next.config.js, and configures Vite automatically. No vite.config.ts required for basic usage.

​
Verify Your Setup

Once you’ve completed any of the above options, verify everything is working: 
vinext dev
# or
npm run dev
You should see your app running with Vite’s fast HMR. Try making a change to a component and watch it update instantly!

​
Check Compatibility

Before fully migrating, it’s a good idea to check your project for compatibility issues: 
vinext check
This scans your Next.js app and produces a compatibility report showing:
  • Which imports are supported
  • Config options that work with vinext
  • Libraries that are compatible
  • Conventions that are supported

​
Deploy to Cloudflare Workers

Once your app is running locally, deploying to Cloudflare Workers is a single command: 
vinext deploy
This command:
  • Auto-generates configuration files (vite.config.ts, wrangler.jsonc, worker/index.ts)
  • Builds your application
  • Deploys to Cloudflare Workers
  • Handles common migration issues automatically
Use vinext deploy --preview to deploy to a preview environment for testing.

​
Next Steps

Now that you have vinext running, here are some things to explore:

Installation Guide

Learn about advanced configuration and customization

CLI Reference

Explore all available vinext commands

API Coverage

See what Next.js features are supported

Live Examples

Check out deployed examples running on Workers

​
Troubleshooting

​
Port Already in Use

If port 3000 is already in use, specify a different port: 
vinext dev --port 3001

​
Module Not Found Errors

Make sure you have the required peer dependencies installed: 
npm install react@^19.2.0 react-dom@^19.2.0 vite@^7.0.0

​
Type Errors

If you see TypeScript errors, make sure your tsconfig.json includes the correct paths. vinext uses vite-tsconfig-paths to resolve path aliases automatically.

​
Build Errors with App Router

For App Router projects, you need @vitejs/plugin-rsc. If you didn’t use vinext init, install it manually: 
npm install -D @vitejs/plugin-rsc
Then create a vite.config.ts:
vite.config.ts
import { defineConfig } from "vite";
import vinext from "vinext";
import rsc from "@vitejs/plugin-rsc";

export default defineConfig({
  plugins: [
    vinext(),
    rsc({
      entries: {
        rsc: "virtual:vinext-rsc-entry",
        ssr: "virtual:vinext-app-ssr-entry",
        client: "virtual:vinext-app-browser-entry",
      },
    }),
  ],
});

​
Common Questions

No! The migration is non-destructive. You can keep Next.js installed and switch between next and vinext as needed. This makes it easy to test vinext without committing fully.
Most of it, yes! vinext supports ~94% of the Next.js 16 API surface. Run vinext check to see what’s supported in your specific project.
Yes! vinext fully supports TypeScript. Your existing tsconfig.json and path aliases work automatically.
Both are fully supported. middleware.ts, proxy.ts (Next.js 16), and API routes in both pages/api/ and app/ directories work as expected.
Currently only Cloudflare Workers is officially supported and tested. Support for other platforms is something we’d like to explore. The vinext start command runs a Node.js server for local testing.

Build docs developers (and LLMs) love

Get started for freeTalk to us