vinext skill for migrating from Next.js
vinext migration skill
The Cloudflare skill walks an agent through moving a Next.js project to vinext, a Vite implementation of the Next.js API: check, config and deploy
- 9,264 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The agent edits `package.json`, renames configs to `.cjs`, removes `next` and installs `vinext` and `vite`
- Publishing with `npx @vinext/cloudflare deploy` builds and ships the app to your Cloudflare account through wrangler
- Other platforms connect through the Nitro plugin and the `NITRO_PRESET` variable, so the build executes code from npm
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/vinext-migration-skillDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent edits `package.json`, renames configs to `.cjs`, removes `next` and installs `vinext` and `vite`
- Publishing with `npx @vinext/cloudflare deploy` builds and ships the app to your Cloudflare account through wrangler
- Other platforms connect through the Nitro plugin and the `NITRO_PRESET` variable, so the build executes code from npm
This is third-party code. Review the repository files before installing.
What it does
The `migrate-to-vinext` skill from the Cloudflare repository walks an agent through moving a project from Next.js to vinext, an implementation of the Next.js API on top of Vite. It activates when you ask to migrate or switch a project and first checks that `next` is in `dependencies` or `devDependencies`: if it is not, the skill stops. The agent then detects the package manager from the lockfile and the router type: an `app/` directory means App Router, a lone `pages/` means Pages Router. Migration runs in five phases. First, `vinext check` produces a report with a compatibility score. Then the recommended `vinext init` installs `vite` (and `@vitejs/plugin-rsc` for App Router), adds `"type": "module"`, renames CommonJS configs to `.cjs`, appends the `dev:vinext` and `build:vinext` scripts, creates a minimal `vite.config.ts` and adds `/dist/` and `.vinext/` to `.gitignore`. The existing Next.js setup keeps working alongside. If `init` does not fit, there is a manual path: remove `next`, install `vinext` and `vite`, replace the commands in scripts. The fourth phase is optional: publishing to Cloudflare Workers with `npx @vinext/cloudflare deploy` or to other platforms through the Nitro plugin. The last phase starts the development server and checks the main routes. The skill forbids changing application code and rewriting `next/*` imports, copying webpack and Turbopack settings and removing `next.config.js`. Cloudflare bindings such as D1, R2 and KV are wired through `import { env } from "cloudflare:workers"`.
Who it is for. For Next.js developers who want to check a project's compatibility with vinext and move it to Vite with Claude Code, Cursor, Codex or OpenCode.
Good fit when
- You want to know in advance which features of a Next.js project vinext does not support: `vinext check` gives a compatibility score
- A project on App Router or Pages Router should move to Vite without changing application code
- The app needs to go to Cloudflare Workers with D1, R2 or KV bindings
- The app needs to run on Node.js, Vercel, Netlify or Deno Deploy through the Nitro plugin
- After the move you need to sort out ESM, third-party package or deployment errors using the `troubleshooting.md` reference
Not a fit when
- There is no `next` in `package.json`: the skill stops at this check
- The project depends heavily on Cache Components and Partial Prerendering: vinext implements them only partially, and the `use cache` directive is suggested instead of PPR
- You need a stable release with no trials: the authors say vinext is under active development and does not yet replace Next.js for every application
- You want to stay on the `next build` pipeline: vinext does not use its output
Example request
Check whether vinext fits this Next.js project and, if it does, migrate it with vinext init and start the dev serverLimitations
- The project is under active development: the authors warn that vinext does not yet replace Next.js for every application, especially in newer App Router features, and ask you to evaluate compatibility on your own code. According to Cloudflare, the repository was built with AI in one week.
- `next/image` (remote images through `@unpic` with no build-time optimization) and `next/font/google` (loaded from a CDN) are partly supported. Domain-based i18n does not work, `next/jest` is replaced by Vitest, and webpack and Turbopack settings are ignored.
- Native modules such as `sharp`, `satori` and `lightningcss` can fail in App Router development mode, with wider support in production builds. The `runtime` and `preferredRegion` parameters do not choose where code runs.
- For Cloudflare bindings the skill requires `cloudflare:workers` and calls `getPlatformProxy()` and custom worker entries outdated.
- `vinext init` targets Cloudflare by default, and the agent must ask you for the target and then pass `--platform=cloudflare` or `--platform=node`. MIT license.
How to disable. Delete the `migrate-to-vinext` folder from the agent's skills directory. To undo the migration itself, revert the changes in `package.json`, `vite.config.ts` and `.gitignore` with git: the old `next dev` and `next build` commands keep working after `vinext init` until you remove the `next` package.
FAQ
How do I install the skill and start the migration?
Run `npx skills add cloudflare/vinext`, open the Next.js project in Claude Code, OpenCode, Cursor or Codex and say "migrate this project to vinext". The skill checks compatibility, installs dependencies, creates the config and starts the development server. A direct migration without an agent is done by `vinext init`.
What does vinext init change?
The command runs the check, installs `vite` and `@vitejs/plugin-rsc`, adds `"type": "module"`, renames CommonJS configs to `.cjs`, appends the `dev:vinext` and `build:vinext` scripts, creates `vite.config.ts` and edits `.gitignore`. The operation is non-destructive: Next.js keeps working alongside, so you can try `dev:vinext` first.
Do I need to rewrite next/link and next/image imports?
No. vinext replaces `next/*` imports on its own, so the skill forbids changing them to `vinext/*`. The `app/` and `pages/` directories and `next.config.js` stay as they are, and the config is read for redirects, headers, `basePath`, `i18n` and environment variables.
Where can I deploy the migrated app?
To Cloudflare Workers with `npx @vinext/cloudflare deploy`: it has the deepest support, including bindings and cache. Other platforms go through the Nitro plugin, and `NITRO_PRESET` sets the target: `vercel`, `netlify`, `deno_deploy` or `node`.
How do I reach D1, R2 and KV?
In a server component, route handler or server action import `env` from `cloudflare:workers`. Bindings are declared in `wrangler.jsonc`, and `wrangler types` generates TypeScript types. This works without a custom worker entry.
What should I check after the move?
Run the generated `dev:vinext` script or `npx vite dev`, make sure the server starts without errors, open the key routes and show the full output if something fails. Common ESM, third-party package and Cloudflare errors are covered in `references/troubleshooting.md`.
Discussion
No questions or reviews yet.
Related
SkillsOfficial Claude Code plugin from the Next.js repo: adopting Cache Components and Partial Prefetching, and verifying changes on a running dev server
Vercel Plugin
vercel-plugin
Vercel's official plugin: an ecosystem graph, skills for Next.js, AI SDK, deployment and storage, specialist agents and deploy commands
Vercel skills for agents
Agent Skills
Vercel skills: React and Next.js performance, UI checks by guidelines, React Native, component composition, and deployment
A skill that points the agent to ready VueUse composables for Vue 3 and Nuxt, with a usage and type reference for each function
A set of skills for Vue 3 development: Composition API practices, router, Pinia, testing, JSX, Options API and debugging
shadcn-vue skill for agents
shadcn-vue skill
The shadcn-vue skill reads your project settings and teaches an agent to add components, forms and themes of the Vue port of shadcn/ui by its rules
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| vinext skill for migrating from Next.js (this entry) | yes | 9,264 | ||
| Next.js skills | no | 143,191 | official skills of Next.js itself: moving to Cache Components and Partial Prefetching without changing the bundler | |
| Next.js DevTools MCP | yes | not required | 834 | connects an agent to a running Next.js 16 or newer dev server: errors, routes, logs |
README in short
The front page opens with a link to Cloudflare's announcement, a warning about active development and a list of what works and what is unfinished. Next come a quick start with `create-vinext-app` and `vinext init`, an optional migration with an agent, manual setup, a reference of commands and plugin options, and deployment to Cloudflare and in Node.js mode. The repository holds the `vinext`, `@vinext/cloudflare` and `create-vinext-app` packages, many samples in `examples/`, end-to-end tests and benchmarks. The skill sits in `.agents/skills/migrate-to-vinext` with three references: compatibility, config examples and error troubleshooting.
README badge
Original SKILL.md
--- 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: