Quick Start

Get started with vinext in 5 minutes. Create a new project or migrate an existing Next.js app.

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.

Option 1: Automated Migration (Recommended)

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:

Development Server

vinext dev
# or
npm run dev

vinext build

vinext start

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

Do I need to remove Next.js dependencies?

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.

Will my existing Next.js code work?

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.

Can I use TypeScript?

Yes! vinext fully supports TypeScript. Your existing tsconfig.json and path aliases work automatically.

What about my middleware and API routes?

Both are fully supported. middleware.ts, proxy.ts (Next.js 16), and API routes in both pages/api/ and app/ directories work as expected.

Can I deploy to platforms other than Cloudflare Workers?

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.