delovable

name	delovable
description	Migrate Lovable, Bolt.new or any Vite+React+Supabase project to Next.js 15 App Router + Clerk + Biome + Bun. Use when the user says "migrate from lovable", "convert lovable to nextjs", "delovable", "graduate from lovable", "move off lovable", "lovable to production", or wants to convert a Vite SPA to Next.js. Also trigger when the user has a project with lovable-tagger, vite_react_shadcn_ts, or .bolt/ directory and wants to make it production-ready.
allowed-tools	WebFetch

delovable

Migrate a vibecoded project (Lovable, Bolt.new, generic Vite+React) to a production-ready Next.js 15 stack.

This is not just a file converter. Each step explains WHY the change matters, connecting to real engineering concepts. The user should understand their code better after the migration, not just have different files.

Target Stack

From	To
Vite	Next.js 15 (App Router)
React Router	File-based routing
Supabase Auth	Clerk
ESLint/Prettier	Biome
npm	Bun
SPA (client-only)	Server Components + client where needed
VITE_* env vars	NEXT_PUBLIC_* + server-only

Supabase Postgres stays as the database. Data migration is out of scope.

Detection

Before starting, confirm the project is a vibecoded SPA. Check for >= 2 of these:

Signal	Confidence
package.json name is "vite_react_shadcn_ts"	Lovable (certain)
lovable-tagger in devDependencies	Lovable (certain)
.lovable/ directory exists	Lovable (certain)
.bolt/ directory exists	Bolt.new (certain)
vite + react-router-dom + @supabase/supabase-js in deps	Likely vibecoded
src/integrations/supabase/client.ts exists	Lovable pattern
src/pages/Index.tsx (capital I)	Lovable convention

If none match, ask the user to confirm before proceeding.

Migration Flow

The migration runs in 5 phases. Phases 1 and 5 are automatic. Phases 2, 3, 4 are guided (explain what's happening and why).

Phase 1: Scaffold (automatic)

Create the Next.js project alongside the existing code:

1. Run bunx create-next-app@latest . --ts --tailwind --app --src-dir --import-alias "@/*" --no-eslint --turbopack in a new directory (or transform in-place if the user prefers)
2. Install deps: bun add @clerk/nextjs sonner @tanstack/react-query
3. Install Biome: bun add -d @biomejs/biome
4. Copy src/components/ as-is (shadcn/ui is compatible, components.json just needs "rsc": true)
5. Copy src/lib/utils.ts as-is (the cn() function is universal)
6. Copy src/hooks/ (add 'use client' to each file)
7. Copy src/index.css (Tailwind directives and CSS variables work in Next.js)
8. Update components.json to set "rsc": true

Why scaffold first: The project structure changes fundamentally. Vite uses index.html + main.tsx as entry points. Next.js uses app/layout.tsx + app/page.tsx. Building the new structure first, then migrating content into it, is less error-prone than trying to transform in-place.

Phase 2: Routes (guided)

Read references/route-mapping.md for the full pattern.

The core idea: Lovable puts all pages in src/pages/ and wires them together in App.tsx with React Router. Next.js uses the filesystem itself as the router, each folder in app/ becomes a URL path.

1. Parse App.tsx for <Route path="..." element={<Component />} /> entries
2. For each route, create the corresponding app/{path}/page.tsx
3. Move the component content into the page file
4. Wrap interactive components with 'use client' where needed (forms, useState, onClick)
5. Move provider wrapping (QueryClientProvider, TooltipProvider, Toaster, Sonner) into app/layout.tsx

Explain to the user:

"Lovable uses React Router, which means all routing logic lives in one App.tsx file. Next.js uses file-based routing, where the folder structure IS the routes. This means adding a new page is just creating a new folder, no router config needed. It also enables each page to be a Server Component by default, which means faster initial loads and better SEO."

Phase 3: Auth (guided)

Read references/auth-migration.md for the full Supabase-to-Clerk conversion.

This is the most impactful change. Lovable uses Supabase Auth with client-side session checks (anon keys in the browser). Clerk uses middleware-based auth (server-side verification before the page even loads).

1. Detect auth usage: grep for supabase.auth, AuthContext, useSession, ProtectedRoute
2. Create middleware.ts with Clerk's clerkMiddleware()
3. Add ClerkProvider to app/layout.tsx
4. Replace supabase.auth.getSession() with Clerk's useUser() / useAuth()
5. Replace <ProtectedRoute> wrappers with Clerk's auth() in server components or <SignedIn> / <SignedOut> components
6. Remove src/contexts/AuthContext.tsx and src/integrations/supabase/client.ts auth references
7. Add .env.local with NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY

Explain to the user:

"Supabase Auth sends an anon key to the browser and checks sessions client-side. This means a user can see your page HTML before auth is verified, and the session token can be tampered with. Clerk's middleware runs on the server before the page loads, so unauthenticated users never see protected content. It's also simpler: no AuthContext, no useEffect for session listening, no manual redirect logic."

Phase 4: Data Layer (guided)

1. Find all supabase.from('table').select() calls
2. For calls in components that can be server components: convert to server-side data fetching using createClient from @supabase/supabase-js with server-only env vars
3. For mutations: convert to Server Actions with 'use server'
4. Keep @tanstack/react-query for client-side cache invalidation where needed

Explain to the user:

"In Lovable, every database query runs in the browser, which means the Supabase URL and anon key are exposed in the client bundle. In Next.js, Server Components can fetch data on the server and send only the HTML to the browser. The database credentials never leave the server. This is both more secure and faster, because the server is closer to the database than the user's browser."

Phase 5: Cleanup (automatic)

1. Remove Vite files: vite.config.ts, index.html, src/main.tsx, src/App.tsx, src/App.css
2. Remove Vite deps from package.json: vite, @vitejs/plugin-react-swc, lovable-tagger
3. Remove .lovable/ or .bolt/ directories
4. Convert remaining import.meta.env.VITE_* to process.env.NEXT_PUBLIC_*
5. Create biome.json with standard config
6. Run bunx biome check --write .
7. Run bun dev to verify the app starts
8. If build succeeds, suggest: npx @railly/last30 audit . to check the new score

Post-Migration Checklist

After the migration completes, print this checklist:

Migration complete. Post-migration checklist:

[ ] Set NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY in .env.local
[ ] Set CLERK_SECRET_KEY in .env.local
[ ] Set NEXT_PUBLIC_SUPABASE_URL in .env.local (moved from hardcoded)
[ ] Set SUPABASE_SERVICE_ROLE_KEY in .env.local (server-only, was anon key)
[ ] Run `bun dev` and verify all pages load
[ ] Run `npx @railly/last30 audit .` to check your new score
[ ] Deploy to Vercel: `vercel`

Learn more: https://thelast30.dev

What This Skill Does NOT Do

• Database migration (data stays in Supabase)
• Supabase Edge Functions conversion (document as TODO for the user)
• Custom domain setup
• Payment integration
• Testing setup (recommend as next step)

These are covered by The Last 30% course at thelast30.dev.

References

File	When to read
references/route-mapping.md	Phase 2: detailed React Router to App Router patterns
references/auth-migration.md	Phase 3: Supabase Auth to Clerk step-by-step