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/*

Installation

New project (migrate from Next.js)

# Automated one-command migration
npx vinext init

This will:

1. Run compatibility check (

   vinext check

   )
2. Install

   vite

   ,

   @vitejs/plugin-react

   as devDependencies
3. Install

   @vitejs/plugin-rsc

   ,

   react-server-dom-webpack

   for App Router
4. Add

   "type": "module"

   to

   package.json

5. Rename CJS config files (e.g.

   postcss.config.js

   →

   postcss.config.cjs

   )
6. Add

   dev:vinext

   and

   build:vinext

   scripts
7. 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": {
    "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

vinext dev

vinext build

vinext start

vinext deploy

vinext init

vinext check

vinext lint

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/

pages/

next.config.js

vite.config.ts

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

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

// 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

"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

react()

rsc()

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