vinext — Next.js API on Vite, Deploy Anywhere

Skill by ara.so — Daily 2026 Skills collection.

vinext is a Vite plugin that reimplements the Next.js public API surface (routing, SSR, RSC, next/* imports, CLI) so existing Next.js apps run on Vite instead of the Next.js compiler. It targets ~94% API coverage, supports both Pages Router and App Router, and deploys natively to Cloudflare Workers with optional Nitro support for AWS, Netlify, Vercel, and more.

Installation

New project (migrate from Next.js)

# Automated one-command migration

npx vinext init

This will:

• Run compatibility check (vinext check)

• Install vite, @vitejs/plugin-react as devDependencies

• Install @vitejs/plugin-rsc, react-server-dom-webpack for App Router

• Add "type": "module" to package.json

• Rename CJS config files (e.g. postcss.config.js → postcss.config.cjs)

• Add dev:vinext and build:vinext scripts

• Generate a minimal vite.config.ts

Migration is non-destructive — Next.js still works alongside vinext.

Manual installation

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

# App Router only:

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

Update package.json scripts:

{

  "scripts": {

    "dev": "vinext dev",

    "build": "vinext build",

    "start": "vinext start",

    "deploy": "vinext deploy"

  }

}

Agent Skill (AI-assisted migration)

npx skills add cloudflare/vinext

# Then in your AI tool: "migrate this project to vinext"

CLI Reference

Command

Description

vinext dev

Start dev server with HMR

vinext build

Production build

vinext start

Local production server for testing

vinext deploy

Build + deploy to Cloudflare Workers

vinext init

Automated migration from Next.js

vinext check

Scan for compatibility issues before migrating

vinext lint

Delegate to eslint or oxlint

CLI Options

vinext dev -p 3001 -H 0.0.0.0

vinext deploy --preview

vinext deploy --env staging --name my-app

vinext deploy --skip-build --dry-run

vinext deploy --experimental-tpr

vinext init --port 3001 --skip-check --force

Configuration

vinext auto-detects app/ or pages/ directory and loads next.config.js automatically. No vite.config.ts is required for basic usage.

Minimal vite.config.ts

import { defineConfig } from 'vite'

import react from '@vitejs/plugin-react'

import { vinext } from 'vinext/vite'

export default defineConfig({

  plugins: [

    react(),

    vinext(),

  ],

})

App Router vite.config.ts

import { defineConfig } from 'vite'

import react from '@vitejs/plugin-react'

import rsc from '@vitejs/plugin-rsc'

import { vinext } from 'vinext/vite'

export default defineConfig({

  plugins: [

    react(),

    rsc(),

    vinext(),

  ],

})

Cloudflare Workers with bindings

import { defineConfig } from 'vite'

import react from '@vitejs/plugin-react'

import { vinext } from 'vinext/vite'

import { cloudflare } from '@cloudflare/vite-plugin'

export default defineConfig({

  plugins: [

    cloudflare(),

    react(),

    vinext(),

  ],

})

Other platforms via Nitro

import { defineConfig } from 'vite'

import react from '@vitejs/plugin-react'

import { vinext } from 'vinext/vite'

import nitro from 'vite-plugin-nitro'

export default defineConfig({

  plugins: [

    react(),

    vinext(),

    nitro({ preset: 'vercel' }), // or 'netlify', 'aws-amplify', 'deno-deploy', etc.

  ],

})

Project Structure

vinext uses the same directory conventions as Next.js — no changes required:

my-app/

├── app/                  # App Router (auto-detected)

│   ├── layout.tsx

│   ├── page.tsx

│   └── api/route.ts

├── pages/                # Pages Router (auto-detected)

│   ├── index.tsx

│   └── api/hello.ts

├── public/               # Static assets

├── next.config.js        # Loaded automatically

├── package.json

└── vite.config.ts        # Optional for basic usage

Code Examples

Pages Router — SSR page

// pages/index.tsx

import type { GetServerSideProps, InferGetServerSidePropsType } from 'next'

type Props = { data: string }

export const getServerSideProps: GetServerSideProps<Props> = async (ctx) => {

  return { props: { data: 'Hello from SSR' } }

}

export default function Home({ data }: InferGetServerSidePropsType<typeof getServerSideProps>) {

  return <h1>{data}</h1>

}

Pages Router — Static generation

// pages/posts/[id].tsx

import type { GetStaticPaths, GetStaticProps } from 'next'

export const getStaticPaths: GetStaticPaths = async () => {

  return {

    paths: [{ params: { id: '1' } }, { params: { id: '2' } }],

    fallback: false,

  }

}

export const getStaticProps: GetStaticProps = async ({ params }) => {

  return { props: { id: params?.id } }

}

export default function Post({ id }: { id: string }) {

  return <p>Post {id}</p>

}

Pages Router — API route

// pages/api/hello.ts

import type { NextApiRequest, NextApiResponse } from 'next'

export default function handler(req: NextApiRequest, res: NextApiResponse) {

  res.status(200).json({ message: 'Hello from vinext' })

}

App Router — Server Component

// app/page.tsx

export default async function Page() {

  const data = await fetch('https://api.example.com/data').then(r => r.json())

  return <main>{data.title}</main>

}

App Router — Route Handler

// app/api/route.ts

import { NextRequest, NextResponse } from 'next/server'

export async function GET(request: NextRequest) {

  return NextResponse.json({ status: 'ok' })

}

export async function POST(request: NextRequest) {

  const body = await request.json()

  return NextResponse.json({ received: body })

}

App Router — Server Action

// app/actions.ts

'use server'

export async function submitForm(formData: FormData) {

  const name = formData.get('name')

  // server-side logic here

  return { success: true, name }

}

// app/form.tsx

'use client'

import { submitForm } from './actions'

export function Form() {

  return (

    <form action={submitForm}>

      <input name="name" />

      <button type="submit">Submit</button>

    </form>

  )

}

Middleware

// middleware.ts

import { NextResponse } from 'next/server'

import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {

  const token = request.cookies.get('token')

  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {

    return NextResponse.redirect(new URL('/login', request.url))

  }

  return NextResponse.next()

}

export const config = {

  matcher: ['/dashboard/:path*'],

}

Cloudflare Workers — Bindings access

// app/api/kv/route.ts

import { NextRequest, NextResponse } from 'next/server'

import { getCloudflareContext } from 'cloudflare:workers'

export async function GET(request: NextRequest) {

  const { env } = getCloudflareContext()

  const value = await env.MY_KV.get('key')

  return NextResponse.json({ value })

}

Image optimization

// app/page.tsx

import Image from 'next/image'

export default function Page() {

  return (

    <Image

      src="/hero.png"

      alt="Hero"

      width={800}

      height={400}

      priority

    />

  )

}

Link and navigation

// app/nav.tsx

'use client'

import Link from 'next/link'

import { useRouter, usePathname } from 'next/navigation'

export function Nav() {

  const router = useRouter()

  const pathname = usePathname()

  return (

    <nav>

      <Link href="/">Home</Link>

      <Link href="/about">About</Link>

      <button onClick={() => router.push('/dashboard')}>Dashboard</button>

    </nav>

  )

}

Deployment

Cloudflare Workers

# Authenticate (once)

wrangler login

# Deploy

vinext deploy

# Deploy to preview

vinext deploy --preview

# Deploy to named environment

vinext deploy --env production --name my-production-app

For CI/CD, set CLOUDFLARE_API_TOKEN environment variable instead of wrangler login.

wrangler.toml (Cloudflare config)

name = "my-app"

compatibility_date = "2024-01-01"

compatibility_flags = ["nodejs_compat"]

[[kv_namespaces]]

binding = "MY_KV"

id = "your-kv-namespace-id"

[[r2_buckets]]

binding = "MY_BUCKET"

bucket_name = "my-bucket"

Netlify / Vercel / AWS via Nitro

npm install -D vite-plugin-nitro

# Then add nitro plugin to vite.config.ts with your target preset

# nitro({ preset: 'netlify' })

# nitro({ preset: 'vercel' })

# nitro({ preset: 'aws-amplify' })

next.config.js Support

vinext loads your existing next.config.js automatically:

// next.config.js

/** @type {import('next').NextConfig} */

const nextConfig = {

  images: {

    remotePatterns: [

      { protocol: 'https', hostname: 'images.example.com' },

    ],

  },

  env: {

    MY_VAR: process.env.MY_VAR,

  },

  redirects: async () => [

    { source: '/old', destination: '/new', permanent: true },

  ],

  rewrites: async () => [

    { source: '/api/:path*', destination: 'https://backend.example.com/:path*' },

  ],

}

module.exports = nextConfig

Compatibility Check

Run before migrating to identify unsupported features:

npx vinext check

This scans for:

• Unsupported next.config.js options

• Deprecated Pages Router APIs

• Experimental Next.js features not yet supported

• CJS config file conflicts

Common Patterns

Environment variables

Works the same as Next.js — .env, .env.local, .env.production:

# .env.local

NEXT_PUBLIC_API_URL=https://api.example.com

DATABASE_URL=$DATABASE_URL

// Accessible in client code (NEXT_PUBLIC_ prefix)

const apiUrl = process.env.NEXT_PUBLIC_API_URL

// Server-only

const dbUrl = process.env.DATABASE_URL

TypeScript path aliases

// tsconfig.json — works as-is

{

  "compilerOptions": {

    "paths": {

      "@/*": ["./src/*"]

    }

  }

}

Tailwind CSS

npm install -D tailwindcss postcss autoprefixer

# Rename postcss.config.js → postcss.config.cjs (vinext init does this automatically)

// postcss.config.cjs

module.exports = {

  plugins: {

    tailwindcss: {},

    autoprefixer: {},

  },

}

Troubleshooting

ESM conflicts with CJS config files

# vinext init handles this automatically, or rename manually:

mv postcss.config.js postcss.config.cjs

mv tailwind.config.js tailwind.config.cjs

Ensure package.json has "type": "module".

vinext init overwrites existing vite.config.ts

vinext init --force

Skip compatibility check during init

vinext init --skip-check

Custom port

vinext dev -p 3001

vinext init --port 3001

wrangler not authenticated for deploy

wrangler login

# or set env var:

export CLOUDFLARE_API_TOKEN=your_token_here

Dry-run deploy to verify config

vinext deploy --dry-run

App Router multi-environment build issues

App Router builds produce three environments (RSC + SSR + client). If you see build errors, ensure all three plugins are installed:

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

And your vite.config.ts includes both react() and rsc() plugins in the correct order.

What's Supported (~94% of Next.js API)

• ✅ Pages Router (SSR, SSG, ISR, API routes)

• ✅ App Router (RSC, Server Actions, Route Handlers, Layouts, Loading, Error boundaries)

• ✅ Middleware

• ✅ next/image, next/link, next/router, next/navigation, next/head

• ✅ next/font, next/dynamic

• ✅ next.config.js (redirects, rewrites, headers, env, images)

• ✅ Cloudflare Workers native deployment with bindings

• ✅ HMR in development

• ✅ TypeScript, Tailwind CSS, CSS Modules

• ⚠️ Experimental Next.js features — lower priority

• ❌ Undocumented Vercel-specific behavior — intentionally not supported