Skip to content

Commit e9c9c80

Browse files
amondnetamondnet
authored
feat(vinext): add vinext plugin to marketplace (#138)
* feat(vinext): add vinext plugin to marketplace Add vinext plugin for migrating Next.js projects to the Vite-based reimplementation. Includes compatibility scanning, package replacement, Vite config generation, ESM conversion, and deployment setup skill. - Add plugin manifest and migrate-to-vinext skill with references - Register vinext in marketplace.json and README - Configure release-please for vinext component versioning * chore: apply AI code review suggestions Add author field to vinext plugin.json crediting upstream Cloudflare organization.
1 parent fe1cb78 commit e9c9c80

9 files changed

Lines changed: 659 additions & 0 deletions

File tree

‎.claude-plugin/marketplace.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -495,6 +495,14 @@
495495
"keywords": ["wordpress", "blocks", "themes", "plugins", "gutenberg", "php"],
496496
"tags": ["framework", "cms"],
497497
"source": "./plugins/wordpress"
498+
},
499+
{
500+
"name": "vinext",
501+
"description": "Migrates Next.js projects to vinext (Vite-based Next.js reimplementation) — compatibility scanning, package replacement, Vite config generation, ESM conversion, and deployment setup",
502+
"category": "framework",
503+
"keywords": ["vinext", "nextjs", "vite", "migration", "cloudflare"],
504+
"tags": ["framework", "migration"],
505+
"source": "./plugins/vinext"
498506
}
499507
]
500508
}

‎README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -242,6 +242,11 @@ Expert-level WordPress knowledge for AI coding assistants — blocks, themes, pl
242242

243243
**Install:** `/plugin install wordpress@pleaseai` | **Source:** [plugins/wordpress](https://github.com/pleaseai/claude-code-plugins/tree/main/plugins/wordpress)
244244

245+
#### Vinext
246+
Migrates Next.js projects to vinext (Vite-based Next.js reimplementation) — compatibility scanning, package replacement, Vite config generation, ESM conversion, and deployment setup.
247+
248+
**Install:** `/plugin install vinext@pleaseai` | **Source:** [plugins/vinext](https://github.com/pleaseai/claude-code-plugins/tree/main/plugins/vinext)
249+
245250
## Quick Start
246251

247252
The fastest way to get started — install the marketplace and let the plugin recommender auto-detect what you need:
@@ -320,6 +325,7 @@ Once the marketplace is added, install any plugin individually:
320325
/plugin install chat-sdk@pleaseai
321326
/plugin install docus@pleaseai
322327
/plugin install wordpress@pleaseai
328+
/plugin install vinext@pleaseai
323329
```
324330

325331
## What Are Claude Code Plugins?

‎plugins/vinext/.agents/skills/migrate-to-vinext/SKILL.md‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
---
2+
name: migrate-to-vinext
3+
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).
4+
---
5+
6+
# Migrate Next.js to vinext
7+
8+
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.
9+
10+
## FIRST: Verify Next.js Project
11+
12+
Confirm `next` is in `dependencies` or `devDependencies` in `package.json`. If not found, STOP — this skill does not apply.
13+
14+
Detect the package manager from the lockfile:
15+
16+
| Lockfile | Manager | Install | Uninstall |
17+
| --------------------------- | ------- | ------------- | --------------- |
18+
| `pnpm-lock.yaml` | pnpm | `pnpm add` | `pnpm remove` |
19+
| `yarn.lock` | yarn | `yarn add` | `yarn remove` |
20+
| `bun.lockb` / `bun.lock` | bun | `bun add` | `bun remove` |
21+
| `package-lock.json` or none | npm | `npm install` | `npm uninstall` |
22+
23+
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.
24+
25+
## Quick Reference
26+
27+
| Command | Purpose |
28+
| --------------- | ---------------------------------------------------------------------- |
29+
| `vinext check` | Scan project for compatibility issues, produce scored report |
30+
| `vinext init` | Automated migration — installs deps, generates config, converts to ESM |
31+
| `vinext dev` | Development server with HMR |
32+
| `vinext build` | Production build (multi-environment for App Router) |
33+
| `vinext start` | Local production server |
34+
| `vinext deploy` | Build and deploy to Cloudflare Workers |
35+
36+
## Phase 1: Check Compatibility
37+
38+
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.
39+
40+
See [references/compatibility.md](references/compatibility.md) for supported/unsupported features and ecosystem library status.
41+
42+
## Phase 2: Automated Migration (Recommended)
43+
44+
Run `vinext init`. This command:
45+
46+
1. Runs `vinext check` for a compatibility report
47+
2. Installs `vite` as a devDependency (and `@vitejs/plugin-rsc` for App Router)
48+
3. Adds `"type": "module"` to package.json
49+
4. Renames CJS config files (e.g., `postcss.config.js` → `.cjs`) to avoid ESM conflicts
50+
5. Adds `dev:vinext` and `build:vinext` scripts to package.json
51+
6. Generates a minimal `vite.config.ts`
52+
53+
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.
54+
55+
If `vinext init` succeeds, skip to Phase 4 (Verify). If it fails or the user prefers manual control, continue to Phase 3.
56+
57+
## Phase 3: Manual Migration
58+
59+
Use this as a fallback when `vinext init` doesn't work or the user wants full control.
60+
61+
### 3a. Replace packages
62+
63+
```bash
64+
# Example with npm:
65+
npm uninstall next
66+
npm install vinext
67+
npm install -D vite
68+
# App Router only:
69+
npm install -D @vitejs/plugin-rsc
70+
```
71+
72+
### 3b. Update scripts
73+
74+
Replace all `next` commands in `package.json` scripts:
75+
76+
| Before | After | Notes |
77+
| ------------ | -------------- | -------------------------- |
78+
| `next dev` | `vinext dev` | Dev server with HMR |
79+
| `next build` | `vinext build` | Production build |
80+
| `next start` | `vinext start` | Local production server |
81+
| `next lint` | `vinext lint` | Delegates to eslint/oxlint |
82+
83+
Preserve flags: `next dev --port 3001` → `vinext dev --port 3001`.
84+
85+
### 3c. Convert to ESM
86+
87+
Add `"type": "module"` to package.json. Rename any CJS config files:
88+
89+
- `postcss.config.js` → `postcss.config.cjs`
90+
- `tailwind.config.js` → `tailwind.config.cjs`
91+
- Any other `.js` config that uses `module.exports`
92+
93+
### 3d. Generate vite.config.ts
94+
95+
See [references/config-examples.md](references/config-examples.md) for config variants per router and deployment target.
96+
97+
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.
98+
99+
**Pages Router (minimal):**
100+
101+
```ts
102+
import vinext from "vinext";
103+
import { defineConfig } from "vite";
104+
export default defineConfig({ plugins: [vinext()] });
105+
```
106+
107+
**App Router (minimal):**
108+
109+
```ts
110+
import vinext from "vinext";
111+
import { defineConfig } from "vite";
112+
export default defineConfig({ plugins: [vinext()] });
113+
```
114+
115+
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.
116+
117+
## Phase 4: Deployment (Optional)
118+
119+
### Option A: Cloudflare Workers (recommended for Cloudflare)
120+
121+
If the user wants to deploy to Cloudflare Workers, use `vinext deploy`. It auto-generates `wrangler.jsonc`, worker entry, and Vite config if missing, installs `@cloudflare/vite-plugin` and `wrangler`, then builds and deploys.
122+
123+
For manual setup or custom worker entries, see [references/config-examples.md](references/config-examples.md).
124+
125+
#### Cloudflare Bindings (D1, R2, KV, AI, etc.)
126+
127+
To access Cloudflare bindings (D1, R2, KV, AI, Queues, Durable Objects, etc.), use `import { env } from "cloudflare:workers"` in any server component, route handler, or server action:
128+
129+
```tsx
130+
import { env } from "cloudflare:workers";
131+
132+
export default async function Page() {
133+
const result = await env.DB.prepare("SELECT * FROM posts").all();
134+
return <div>{JSON.stringify(result)}</div>;
135+
}
136+
```
137+
138+
This works because `@cloudflare/vite-plugin` runs server environments in workerd, where `cloudflare:workers` is a native module. No custom worker entry, no `getPlatformProxy()`, no special configuration needed. Just import and use.
139+
140+
Bindings must be defined in `wrangler.jsonc`. For TypeScript types, run `wrangler types`.
141+
142+
**IMPORTANT:** Do not use `getPlatformProxy()`, `getRequestContext()`, or custom worker entries with `fetch(request, env)` to access bindings. These are older patterns. `cloudflare:workers` is the recommended approach and works out of the box with vinext.
143+
144+
### Option B: Other platforms (via Nitro)
145+
146+
For deploying to Vercel, Netlify, AWS, Deno Deploy, or any other [Nitro-supported platform](https://v3.nitro.build/deploy), add the Nitro Vite plugin:
147+
148+
```bash
149+
npm install nitro
150+
```
151+
152+
```ts
153+
// vite.config.ts
154+
import { defineConfig } from "vite";
155+
import vinext from "vinext";
156+
import { nitro } from "nitro/vite";
157+
158+
export default defineConfig({
159+
plugins: [vinext(), nitro()],
160+
});
161+
```
162+
163+
Build and deploy:
164+
165+
```bash
166+
NITRO_PRESET=vercel npx vite build # Vercel
167+
NITRO_PRESET=netlify npx vite build # Netlify
168+
NITRO_PRESET=deno_deploy npx vite build # Deno Deploy
169+
NITRO_PRESET=node npx vite build # Node.js server
170+
```
171+
172+
Nitro auto-detects the platform in most CI/CD environments, so the preset is often unnecessary.
173+
174+
**Note:** For Cloudflare Workers, Nitro works but the native integration (`vinext deploy` / `@cloudflare/vite-plugin`) is recommended for the best developer experience with `cloudflare:workers` bindings, KV caching, and one-command deploys.
175+
176+
## Phase 5: Verify
177+
178+
1. Run `vinext dev` to start the development server
179+
2. Confirm the server starts without errors
180+
3. Navigate key routes and check functionality
181+
4. Report the result to the user — if errors occur, share full output
182+
183+
See [references/troubleshooting.md](references/troubleshooting.md) for common migration errors.
184+
185+
## Known Limitations
186+
187+
| Feature | Status |
188+
| ----------------------------- | --------------------------------------------------------- |
189+
| `next/image` optimization | Remote images via @unpic; no build-time optimization |
190+
| `next/font/google` | CDN-loaded, not self-hosted |
191+
| Domain-based i18n | Not supported; path-prefix i18n works |
192+
| `next/jest` | Not supported; use Vitest |
193+
| Turbopack/webpack config | Ignored; use Vite plugins instead |
194+
| `runtime` / `preferredRegion` | Route segment configs ignored |
195+
| PPR (Partial Prerendering) | Use `"use cache"` directive instead (Next.js 16 approach) |
196+
197+
## Anti-patterns
198+
199+
- **Do not modify `app/`, `pages/`, or application code.** vinext shims all `next/*` imports — no import rewrites needed.
200+
- **Do not rewrite `next/*` imports** to `vinext/*` in application code. Imports like `next/image`, `next/link`, `next/server` resolve automatically.
201+
- **Do not copy webpack/Turbopack config** into Vite config. Use Vite-native plugins instead.
202+
- **Do not skip the compatibility check.** Run `vinext check` before migration to surface issues early.
203+
- **Do not remove `next.config.js`** unless replacing it with `next.config.ts` or `.mjs`. vinext reads it for redirects, rewrites, headers, basePath, i18n, images, and env config.
204+
- **Do not use `getPlatformProxy()` or custom worker entries for bindings.** Use `import { env } from "cloudflare:workers"` instead. This is the modern pattern and works out of the box with vinext and `@cloudflare/vite-plugin`.
205+
- **For Cloudflare Workers, prefer the native integration over Nitro.** `vinext deploy` / `@cloudflare/vite-plugin` provides the best experience with `cloudflare:workers` bindings, KV caching, and image optimization. Nitro works for Cloudflare but the native setup is recommended.

‎plugins/vinext/.agents/skills/migrate-to-vinext/references/compatibility.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Compatibility Reference
2+
3+
## Supported next/\* Imports
4+
5+
All of these resolve automatically to vinext shims. Do not rewrite imports in application code.
6+
7+
| Import | Status | Notes |
8+
| ------------------- | ------- | ---------------------------------------------------------------- |
9+
| `next/link` | Full | |
10+
| `next/image` | Partial | Remote images via @unpic; no build-time optimization |
11+
| `next/head` | Full | |
12+
| `next/router` | Full | Pages Router |
13+
| `next/navigation` | Full | App Router |
14+
| `next/server` | Full | NextRequest, NextResponse, cookies, userAgent, after, connection |
15+
| `next/headers` | Full | |
16+
| `next/dynamic` | Full | |
17+
| `next/script` | Full | |
18+
| `next/font/google` | Partial | CDN-loaded, not self-hosted |
19+
| `next/font/local` | Partial | Runtime injection |
20+
| `next/og` | Full | Via @vercel/og |
21+
| `next/cache` | Full | Pluggable CacheHandler |
22+
| `next/form` | Full | |
23+
| `next/legacy/image` | Full | |
24+
| `next/error` | Full | |
25+
| `next/config` | Full | |
26+
| `next/document` | Full | Pages Router |
27+
| `next/constants` | Full | |
28+
| `next/amp` | Stub | No-op; AMP deprecated since Next.js 13 |
29+
| `next/web-vitals` | Stub | No-op |
30+
| `server-only` | Full | |
31+
| `client-only` | Full | |
32+
33+
## Routing Features
34+
35+
| Feature | Supported |
36+
| ------------------------------------------ | --------- |
37+
| Pages Router (`pages/`) | Yes |
38+
| App Router (`app/`) | Yes |
39+
| Dynamic routes `[param]` | Yes |
40+
| Catch-all `[...slug]` | Yes |
41+
| Optional catch-all `[[...slug]]` | Yes |
42+
| Route groups `(group)` | Yes |
43+
| Parallel routes `@slot` | Yes |
44+
| Intercepting routes `(.)`, `(..)`, `(...)` | Yes |
45+
| Route handlers (`route.ts`) | Yes |
46+
| Middleware / `proxy.ts` (Next.js 16) | Yes |
47+
| i18n (path prefix) | Yes |
48+
| i18n (domain-based) | No |
49+
| `basePath` | Yes |
50+
| `trailingSlash` | Yes |
51+
52+
## Server Features
53+
54+
| Feature | Supported |
55+
| --------------------------------------------- | ---------------------- |
56+
| SSR (streaming) | Yes |
57+
| React Server Components | Yes |
58+
| Server Actions (`"use server"`) | Yes |
59+
| `getStaticProps` / `getStaticPaths` | Yes |
60+
| `getServerSideProps` | Yes |
61+
| ISR (stale-while-revalidate) | Yes |
62+
| `"use cache"` / `cacheLife()` / `cacheTag()` | Yes |
63+
| Metadata API (`metadata`, `generateMetadata`) | Yes |
64+
| `generateStaticParams` | Yes |
65+
| Static export (`output: 'export'`) | Yes |
66+
| `instrumentation.ts` | Yes |
67+
| `connection()` | Yes |
68+
| Pluggable CacheHandler | Yes |
69+
| PPR (Partial Prerendering) | No — use `"use cache"` |
70+
71+
## Route Segment Config
72+
73+
| Config | Supported |
74+
| ----------------- | --------- |
75+
| `revalidate` | Yes |
76+
| `dynamic` | Yes |
77+
| `dynamicParams` | Yes |
78+
| `runtime` | Ignored |
79+
| `preferredRegion` | Ignored |
80+
81+
## next.config.js Options
82+
83+
vinext loads and respects: `redirects`, `rewrites`, `headers`, `basePath`, `trailingSlash`, `i18n` (path prefix), `images`, `env`, `NEXT_PUBLIC_*` env vars, `output`, `serverExternalPackages` (consider using Vite's `ssr.external` instead).
84+
85+
Ignored: `webpack`, `turbopack`, `experimental.turbo`.
86+
87+
## Ecosystem Libraries
88+
89+
Tested and working:
90+
91+
- next-themes
92+
- nuqs
93+
- next-view-transitions
94+
- next-intl
95+
- better-auth
96+
- @vercel/analytics
97+
- tailwindcss
98+
- framer-motion
99+
- shadcn-ui
100+
- lucide-react
101+
- drizzle
102+
- prisma
103+
104+
## Not Supported
105+
106+
These features are intentionally excluded:
107+
108+
- Vercel-specific bindings (@vercel/og edge runtime, Vercel Analytics server bindings)
109+
- AMP (deprecated since Next.js 13)
110+
- `next export` (legacy — use `output: 'export'`)
111+
- Turbopack/webpack configuration
112+
- `next/jest` (use Vitest)
113+
- `create-next-app` scaffolding
114+
- Bug-for-bug parity with undocumented Next.js behavior
115+
- Native Node modules in Workers (sharp, resvg, satori — auto-stubbed in production)

0 commit comments

Comments
 (0)