vinext init

Migrates an existing Next.js project to vinext with a one-command setup. Installs dependencies, configures ESM, generates vite.config.ts, and adds npm scripts.

Usage

vinext init [options]

Options

--port

number

default:"3001"

Dev server port for the vinext script. Can also use the short form -p.

vinext init --port 4000

Creates a dev:vinext script that runs on this port (Next.js dev continues to use port 3000).

--skip-check

flag

Skip the compatibility check step.

vinext init --skip-check

By default, vinext runs a compatibility scan before migration. Use this to skip it.

--force

flag

Overwrite existing vite.config.ts if it exists.

vinext init --force

By default, vinext skips config generation if vite.config.ts already exists.

--help

flag

Show help for this command. Can also use -h.

vinext init --help

What It Does

The init command automates project migration:

// From init.ts:157-257
export async function init(options: InitOptions): Promise<InitResult> {
  // 1. Run compatibility check (shows what will/won't work)
  if (!options.skipCheck) {
    const checkResult = runCheck(root);
    console.log(formatReport(checkResult));
  }
  
  // 2. Install dependencies
  const neededDeps = getInitDeps(isApp);
  const missingDeps = neededDeps.filter(dep => !isDepInstalled(root, dep));
  if (missingDeps.length > 0) {
    installDeps(root, missingDeps);
  }
  
  // 3. Add "type": "module" to package.json
  const renamedConfigs = renameCJSConfigs(root);
  const addedTypeModule = ensureESModule(root);
  
  // 4. Add scripts to package.json
  const addedScripts = addScripts(root, port);
  
  // 5. Generate vite.config.ts
  if (!viteConfigExists || options.force) {
    const configContent = generateViteConfig(isApp);
    fs.writeFileSync("vite.config.ts", configContent);
  }
  
  // 6. Print summary
  console.log("vinext init complete!");
}

1. Compatibility Check

Scans your project and shows a compatibility report:

vinext init

  Running compatibility check...

  vinext compatibility report
  ========================================

  Imports: 8/10 fully supported
    ✓  next/link
    ✓  next/navigation
    ~  next/image — uses @unpic/react (no local optimization yet)
    ✗  next/amp — AMP is not supported

  Config: 5/6 options supported
    ✓  redirects
    ✓  rewrites
    ✗  webpack — Vite replaces webpack

  Libraries: 3/3 compatible
    ✓  next-themes
    ✓  tailwindcss
    ✓  zod

  Project structure:
    ✓  App Router (app/)
    ✓  15 page(s)
    ✓  3 layout(s)
    ✗  Missing "type": "module" in package.json — required for Vite

  ────────────────────────────────────────
  Overall: 85% compatible (20 supported, 2 partial, 2 issues)

See the check command for details on what’s checked.

2. Dependency Installation

Installs required packages:

# Installs: vinext, vite, @vitejs/plugin-rsc
npm install -D vinext vite @vitejs/plugin-rsc

// From init.ts:115-121
export function getInitDeps(isAppRouter: boolean): string[] {
  const deps = ["vinext", "vite"];
  if (isAppRouter) {
    deps.push("@vitejs/plugin-rsc");
  }
  return deps;
}

3. ESM Configuration

Vite requires ESM. vinext automatically:

Renames CJS config files to .cjs extension:
- next.config.js → next.config.cjs
- postcss.config.js → postcss.config.cjs
- tailwind.config.js → tailwind.config.cjs
Adds "type": "module" to package.json:

{
  "name": "my-app",
  "version": "1.0.0",
  "type": "module",  // Added by vinext init
  "scripts": { /* ... */ }
}

After adding "type": "module", .js files are treated as ESM. If you have CommonJS files, rename them to .cjs or convert to ESM.

4. Script Addition

Adds vinext scripts to package.json without overwriting existing ones:

{
  "scripts": {
    "dev": "next dev",              // Unchanged (Next.js still works)
    "dev:vinext": "vite dev --port 3001",  // Added
    "build": "next build",          // Unchanged
    "build:vinext": "vite build",   // Added
    "start": "next start"
  }
}

You can now run:

npm run dev         # Next.js dev server (port 3000)
npm run dev:vinext  # vinext dev server (port 3001)

5. Config Generation

Generates a minimal vite.config.ts:

// From init.ts:63-70
export function generateViteConfig(_isAppRouter: boolean): string {
  return `import vinext from "vinext";
import { defineConfig } from "vite";

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

The vinext() plugin auto-detects App Router and registers @vitejs/plugin-rsc if needed.

If vite.config.ts already exists, vinext skips generation unless you use --force.

Examples

Basic Migration

Migrate with all defaults:

vinext init

Output:

  Running compatibility check...

  [compatibility report]

  Installing vinext, vite, @vitejs/plugin-rsc...

  vinext init complete!

    ✓ Added vinext, vite, @vitejs/plugin-rsc to devDependencies
    ✓ Added "type": "module" to package.json
    ✓ Renamed next.config.js → next.config.cjs
    ✓ Added dev:vinext script
    ✓ Added build:vinext script
    ✓ Generated vite.config.ts

  Next steps:
    npm run dev:vinext    Start the vinext dev server
    npm run dev           Start Next.js (still works as before)

Custom Port

Use a different dev server port:

vinext init --port 4000

Creates:

{
  "scripts": {
    "dev:vinext": "vite dev --port 4000"
  }
}

Skip Compatibility Check

Skip the check if you’ve already run vinext check:

vinext check        # Run check separately
vinext init --skip-check

Force Overwrite Config

Overwrite existing vite.config.ts:

vinext init --force

This will replace your existing vite.config.ts. Back it up first if you have custom configuration.

Non-Destructive Migration

vinext init is non-destructive:

Does NOT modify: next.config.*, tsconfig.json, source files
Does NOT remove: Next.js dependencies or scripts
Safe to run: Your Next.js setup continues to work

You can run both Next.js and vinext side-by-side:

# Terminal 1: Next.js
npm run dev

# Terminal 2: vinext
npm run dev:vinext

After Migration

Start Development Server

npm run dev:vinext

Or directly:

vinext dev

Build for Production

npm run build:vinext

Or:

vinext build

Deploy to Cloudflare Workers

vinext deploy

Manual Migration Steps

If you prefer manual setup:

1. Install Dependencies

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

2. Add “type”: “module”

Edit package.json:

{
  "type": "module"
}

3. Rename CJS Configs

mv next.config.js next.config.cjs
mv postcss.config.js postcss.config.cjs

4. Create vite.config.ts

import { defineConfig } from 'vite'
import vinext from 'vinext'

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

5. Add Scripts

Edit package.json:

{
  "scripts": {
    "dev:vinext": "vite dev --port 3001",
    "build:vinext": "vite build"
  }
}

6. Start Dev Server

npm run dev:vinext

Troubleshooting

”Cannot use import statement outside a module”

You have CommonJS files with require() statements. Either:

Rename them to .cjs:
```
mv some-file.js some-file.cjs
```

Or convert to ESM:

// Before (CommonJS)
const foo = require('./foo')
module.exports = { bar }

// After (ESM)
import foo from './foo'
export { bar }

“Module not found: @vitejs/plugin-rsc”

For App Router projects, ensure the RSC plugin is installed:

npm install -D @vitejs/plugin-rsc

vinext dev Fails on Port 3001

Port is already in use. Use a different port:

vinext init --port 4000

Or change the script manually:

{
  "scripts": {
    "dev:vinext": "vite dev --port 4000"
  }
}

Type Errors After Migration

Run TypeScript typecheck:

npx tsc --noEmit

Common issues:

Missing types: npm install -D @types/node

Vite types: Add to tsconfig.json:

{
  "compilerOptions": {
    "types": ["vite/client"]
  }
}

Rollback

To remove vinext and go back to Next.js only:

Remove vinext scripts from package.json
Remove "type": "module" from package.json
Rename configs back:
```
mv next.config.cjs next.config.js
```

Remove dependencies:

npm uninstall vinext vite @vitejs/plugin-rsc

Delete vite.config.ts

Next Steps

dev Command

Start the development server

check Command

Understand the compatibility report

CLI

Module Shims

Configuration

Cloudflare

Usage

Options

What It Does

1. Compatibility Check

2. Dependency Installation

3. ESM Configuration

4. Script Addition

5. Config Generation

Examples

Basic Migration

Custom Port

Skip Compatibility Check

Force Overwrite Config

Non-Destructive Migration

After Migration

Start Development Server

Build for Production

Deploy to Cloudflare Workers

Manual Migration Steps

1. Install Dependencies

2. Add “type”: “module”

3. Rename CJS Configs

4. Create vite.config.ts

5. Add Scripts

6. Start Dev Server

Troubleshooting

”Cannot use import statement outside a module”

“Module not found: @vitejs/plugin-rsc”

vinext dev Fails on Port 3001

Type Errors After Migration

Rollback

Next Steps

dev Command

check Command

Build docs developers (and LLMs) love

CLI

Module Shims

Configuration

Cloudflare

Documentation Index

​Usage

​Options

​What It Does

​1. Compatibility Check

​2. Dependency Installation

​3. ESM Configuration

​4. Script Addition

​5. Config Generation

​Examples

​Basic Migration

​Custom Port

​Skip Compatibility Check

​Force Overwrite Config

​Non-Destructive Migration

​After Migration

​Start Development Server

​Build for Production

​Deploy to Cloudflare Workers

​Manual Migration Steps

​1. Install Dependencies

​2. Add “type”: “module”

​3. Rename CJS Configs

​4. Create vite.config.ts

​5. Add Scripts

​6. Start Dev Server

​Troubleshooting

​”Cannot use import statement outside a module”

​“Module not found: @vitejs/plugin-rsc”

​vinext dev Fails on Port 3001

​Type Errors After Migration

​Rollback

​Next Steps

dev Command

check Command

Build docs developers (and LLMs) love

Usage

Options

What It Does

1. Compatibility Check

2. Dependency Installation

3. ESM Configuration

4. Script Addition

5. Config Generation

Examples

Basic Migration

Custom Port

Skip Compatibility Check

Force Overwrite Config

Non-Destructive Migration

After Migration

Start Development Server

Build for Production

Deploy to Cloudflare Workers

Manual Migration Steps

1. Install Dependencies

2. Add “type”: “module”

3. Rename CJS Configs

4. Create vite.config.ts

5. Add Scripts

6. Start Dev Server

Troubleshooting

”Cannot use import statement outside a module”

“Module not found: @vitejs/plugin-rsc”

vinext dev Fails on Port 3001

Type Errors After Migration

Rollback

Next Steps