migrate-to-vinext
installsforks
How to install migrate-to-vinext?
cloudflare/vinext/migrate-to-vinext
$npx -y skills add cloudflare/vinext --skill migrate-to-vinextmigrate-to-vinext is an agent skill published from cloudflare/vinext, installable through the skills CLI.
SKILL.md
| 1 | # Migrate Next.js to vinext |
| 2 | |
| 3 | 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. |
| 4 | |
| 5 | ## FIRST: Verify Next.js Project |
| 6 | |
| 7 | Confirm `next` is in `dependencies` or `devDependencies` in `package.json`. If not found, STOP — this skill does not apply. |
| 8 | |
| 9 | Detect the package manager from the lockfile: |
| 10 | |
| 11 | | Lockfile | Manager | Install | Uninstall | |
| 12 | | --------------------------- | ------- | ------------- | --------------- | |
| 13 | | `pnpm-lock.yaml` | pnpm | `pnpm add` | `pnpm remove` | |
| 14 | | `yarn.lock` | yarn | `yarn add` | `yarn remove` | |
| 15 | | `bun.lockb` / `bun.lock` | bun | `bun add` | `bun remove` | |
| 16 | | `package-lock.json` or none | npm | `npm install` | `npm uninstall` | |
| 17 | |
| 18 | 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. |
| 19 | |
| 20 | ## Quick Reference |
| 21 | |
| 22 | | Command | Purpose | |
| 23 | | ---------------------------------- | ---------------------------------------------------------------------- | |
| 24 | | `vinext check` | Scan project for compatibility issues, produce scored report | |
| 25 | | `vinext init` | Automated migration — installs deps, generates config, converts to ESM | |
| 26 | | `vinext dev` | Development server with HMR | |
| 27 | | `vinext build` | Production build (multi-environment for App Router) | |
| 28 | | `vinext start` | Local production server | |
| 29 | | `npx @vinext/cloudflare deploy` | Build and deploy to Cloudflare Workers | |
| 30 | | `vp exec vinext-cloudflare deploy` | Build and deploy to Cloudflare Workers with Vite+ | |
| 31 | |
| 32 | ## Phase 1: Check Compatibility |
| 33 | |
| 34 | 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. |
| 35 | |
| 36 | See [references/compatibility.md](references/compatibility.md) for supported/unsupported features and ecosystem library status. |
| 37 | |
| 38 | ## Phase 2: Automated Migration (Recommended) |
| 39 | |
| 40 | Run `vinext init`. This command: |
| 41 | |
| 42 | 1. Runs `vinext check` for a compatibility report |
| 43 | 2. Installs `vite` as a devDependency (and `@vitejs/plugin-rsc` for App Router) |
| 44 | 3. Adds `"type": "module"` to package.json |
| 45 | 4. Renames CJS config files (e.g., `postcss.config.js` → `.cjs`) to avoid ESM conflicts |
| 46 | 5. Adds `dev:vinext` and `build:vinext` scripts to package.json |
| 47 | 6. Generates a minimal `vite.config.ts` |
| 48 | 7. Adds `/dist/` and `.vinext/` to `.gitignore` |
| 49 | |
| 50 | 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. |
| 51 | |
| 52 | If `vinext init` succeeds, skip to Phase 4 (Verify). If it fails or the user prefers manual control, continue to Phase 3. |
| 53 | |
| 54 | ## Phase 3: Manual Migration |
| 55 | |
| 56 | Use this as a fallback when `vinext init` doesn't work or the user wants full control. |
| 57 | |
| 58 | ### 3a. Replace packages |
| 59 | |
| 60 | ```bash |
| 61 | # Example with npm: |
| 62 | npm uninstall next |
| 63 | npm install vinext |
| 64 | npm install -D vite |
| 65 | # App Router only: |
| 66 | npm install -D @vitejs/plugin-rsc |
| 67 | ``` |
| 68 | |
| 69 | ### 3b. Update scripts |
| 70 | |
| 71 | Replace all `next` commands in `package.json` scripts: |
| 72 | |
| 73 | | Before | After | Notes | |
| 74 | | ------------ | -------------- | -------------------------- | |
| 75 | | `next dev` | `vinext dev` | Dev server with HMR | |
| 76 | | `next build` | `vinext build` | Production build | |
| 77 | | `next start` | `vinext start` | Local production server | |
| 78 | | `next lint` | `vinext lint` | Delegates to eslint/oxlint | |
| 79 | |
| 80 | Preserve flags: `next dev --port 3001` → `vinext dev --port 3001`. |
| 81 | |
| 82 | ### 3c. Convert to ESM |
| 83 | |
| 84 | Add `"type": "module"` to package.json. Rename any CJS config files: |
| 85 | |
| 86 | - `postcss.config.js` → `postcss.config.cjs` |
| 87 | - `tailwind.config.js` → `tailwind.config.cjs` |
| 88 | - Any other `.js` config that uses `module.exports` |
| 89 | |
| 90 | ### 3d. Generate vite.config.ts |
| 91 | |
| 92 | See [references/config-examples.md](references/config-examples.md) for config variants per router and deployment target. |
| 93 | |
| 94 | 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 wor |
People who liked this also viewed
6 picksType
- microsoft-foundryDeploy, evaluate, fine-tune, and manage Foundry agents end-to-end with azd: hosted agent scaffold/run/deploy, prompt agent create, batch eval, continuous eval, prompt optimizer, Agent Optimizer scaffoSkillsJul 2026
- azure-deployExecute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application SkillsJul 2026
- azure-preparePrepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles for the Azure Developer CLI (azd) workflow. USE ONLY when the user explicitly wSkillsJul 2026
- azure-validate--- name: azure-validate description: "Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity pSkillsJul 2026
- azure-aigatewayConfigure Azure API Management as an AI Gateway for AI models, MCP tools, and agents. WHEN: semantic caching, token limit, content safety, load balancing, AI model governance, MCP rate limiting, jailbSkillsJul 2026
- azure-hosted-copilot-sdkOfficial agent plugin providing skills and MCP server configurations for Azure scenarios.SkillsJul 2026
