Migrate To VinextSAFE

Vite plugin that reimplements the Next.js API surface — deploy anywhere

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: migrate-to-vinext
description: Migrates Next.js projects to vinext (Vite-based Next.js reimplementation). Load when asked to migrate, convert, or switch from Next.js to vinext. Handles compatibility scanning, package replacement, Vite config generation, ESM conversion, and deployment setup (Cloudflare Workers natively, other platforms via Nitro).
---

# Migrate Next.js to vinext

vinext reimplements the Next.js API surface on Vite. Existing `app/`, `pages/`, and `next.config.js` work as-is — migration is a package swap, config generation, and ESM conversion. No changes to application code required.

## FIRST: Verify Next.js Project

Confirm `next` is in `dependencies` or `devDependencies` in `package.json`. If not found, STOP — this skill does not apply.

Detect the package manager from the lockfile:

| Lockfile                    | Manager | Install       | Uninstall       |
| --------------------------- | ------- | ------------- | --------------- |
| `pnpm-lock.yaml`            | pnpm    | `pnpm add`    | `pnpm remove`   |
| `yarn.lock`                 | yarn    | `yarn add`    | `yarn remove`   |
| `bun.lockb` / `bun.lock`    | bun     | `bun add`     | `bun remove`    |
| `package-lock.json` or none | npm     | `npm install` | `npm uninstall` |

Detect the router: if an `app/` directory exists at root or under `src/`, it's App Router. If only `pages/` exists, it's Pages Router. Both can coexist.

## Quick Reference

| Command                            | Purpose                                                                |
| ---------------------------------- | ---------------------------------------------------------------------- |
| `vinext check`                     | Scan project for compatibility issues, produce scored report           |
| `vinext init`                      | Automated migration — installs deps, generates config, converts to ESM |
| `npx vite dev`                     | Development server with HMR                                            |
| `npx vite build`                   | Production build (multi-environment for App Router)                    |
| `vinext start`                     | Local production server                                                |
| `npx @vinext/cloudflare deploy`    | Build and deploy to Cloudflare Workers                                 |
| `vp exec vinext-cloudflare deploy` | Build and deploy to Cloudflare Workers with Vite+                      |

## Phase 1: Check Compatibility

Run `vinext check` (install vinext first if needed via `npx vinext check`). Review the scored report. If critical incompatibilities exist, inform the user before proceeding.

See [references/compatibility.md](references/compatibility.md) for supported/unsupported features and ecosystem library status.

## Phase 2: Automated Migration (Recommended)

Run `vinext init`. This command:

1. Runs `vinext check` for a compatibility report
2. Installs `vite` as a devDependency (and `@vitejs/plugin-rsc` for App Router)
3. Adds `"type": "module"` to package.json
4. Renames CJS config files (e.g., `postcss.config.js` → `.cjs`) to avoid ESM conflicts
5. Adds `dev:vinext` and `build:vinext` scripts to package.json
6. Generates a minimal `vite.config.ts`
7. Adds `/dist/` and `.vinext/` to `.gitignore`

This is non-destructive — the existing Next.js setup continues to work alongside vinext. Use the `dev:vinext` script to test before fully switching over.

If `vinext init` succeeds, skip to Phase 4 (Verify). If it fails or the user prefers manual control, continue to Phase 3.

## Phase 3: Manual Migration

Use this as a fallback when `vinext init` doesn't work or the user wants full control.

### 3a. Replace packages

```bash
# Example with npm:
npm uninstall next
npm install vinext
npm install -D vite
# App Router only:
npm install -D @vitejs/plugin-rsc
```

### 3b. Update scripts

Replace all `next` commands in `package.json` scripts:

| Before       | After          | Notes                      |
| ------------ | -------------- | -------------------------- |
| `next dev`   | `vite dev`     | Dev server with HMR        |
| `next build` | `vite build`   | Production build           |
| `next start` | `vinext start` | Local production server    |
| `next lint`  | `vinext lint`  | Delegates to eslint/oxlint |

Preserve Vite-compatible flags: `next dev --port 3001` → `vite dev --port 3001`. Translate Next-only build flags into `vinext()` options in `vite.config.ts` instead of forwarding them to Vite.

### 3c. Convert to ESM

Add `"type": "module"` to package.json. Rename any CJS config files:

- `postcss.config.js` → `postcss.config.cjs`
- `tailwind.config.js` → `tailwind.config.cjs`
- Any other `.js` config that uses `module.exports`

### 3d. Generate vite.config.ts

See [references/config-examples.md](references/config-examples.md) for config variants per router and deployment target.

If the project already has custom Vite config, prefer Vite 8-native keys when editing it: `oxc`, `optimizeDeps.rolldownOptions`, and `build.rolldownOptions`. Older `esbuild` and `build.rollupOptions` settings still work for now but are migration targets.

**Pages Router (minimal):**

```ts
import vinext from "vinext";
import { defineConfig } from "vite";
export default defineConfig({ plugins: [vinext()] });
```

**App Router (minimal):**

```ts
import vinext from "vinext";
import { defineConfig } from "vite";
export default defineConfig({ plugins: [vinext()] });
```

vinext auto-registers `@vitejs/plugin-rsc` for App Router when the `rsc` option is not explicitly `false`. No manual RSC plugin config needed for local development.

### 3e. Update .gitignore

Ensure vinext-generated output and caches are ignored:

```gitignore
/dist/
.vinext/
```

## Phase 4: Deployment (Optional)

### Option A: Cloudflare Workers (recommended for Cloudflare)

If the user wants to deploy to Cloudflare Workers, use `npx @vinext/cloudflare deploy`. With Vite+, use `vp exec vinext-cloudflare deploy

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (1)

CLAUDE.md

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Migrate To Vinext](https://modelsatlas.com/skills/cloudflare/migrate-to-vinext/badge.svg)](https://modelsatlas.com/skills/cloudflare/migrate-to-vinext/)

Not your listing, or something out of date? Claim or update your listing.