How to Convert a Lovable App to Next.js
Lovable can't output Next.js: every project uses Lovable's own stack. To convert, export the code through Git sync, get it running on Next.js as a client-rendered app using the official Vite migration steps, then move routes from React Router to the App Router one at a time and switch Supabase auth to cookie sessions. Check first whether you need it at all: newer Lovable apps already render on the server.
By Hire Lovable Xperts · Last verified: 2026-11-17
Can Lovable build or export a Next.js app?
No. Lovable's FAQ says every project uses the same stack, with no choice of framework. Apps created since 13 May 2026 use TanStack Start, which renders pages on the server; older apps use React with Vite and render in the browser. Getting to Next.js therefore means taking the code out of Lovable's stack, and after the switch you edit it in your own editor, not in Lovable.
Lovable gives you the code two ways: Git sync, which works on any plan and keeps a repository in step with the project, and Download codebase, a .zip on paid plans. Either is a fine starting point. Because Lovable pushes its own edits to the repository's default branch, do the conversion on a separate branch so Lovable and your Next.js work never write to the same place.
Related: Export Lovable code to GitHub
Do you need Next.js, or is Lovable's TanStack Start upgrade enough?
Most people looking for this conversion want pages Google can read. Check your stack before converting: a project with @tanstack/react-start in its package.json dependencies already renders on the server. An older React + Vite project can be upgraded to TanStack Start inside Lovable; Lovable says most upgrades cost 10 to 35 credits and can be reverted from version history.
Lovable warns that some libraries only work in the browser and can break server rendering. That applies to a Next.js conversion just as much: anything that reads window or localStorage while a page renders has to move into client-only code whichever route you take.
| Your project | How pages render today | Cheapest route to server-rendered pages | When Next.js still makes sense |
|---|---|---|---|
| TanStack Start (created since 13 May 2026; @tanstack/react-start in dependencies) | On the server, as finished HTML | Nothing to do | Your team standardises on Next.js, or you are leaving Lovable for good |
| React + Vite (older projects) | In the browser; Lovable serves pre-rendered copies of published pages to verified search engines | Lovable's in-app upgrade to TanStack Start | You want to leave Lovable's stack and own a codebase in a framework your team already runs |
What changes when a Lovable app moves to Next.js?
For a React + Vite Lovable app, five things change: the HTML shell, the entry point, routing, environment variables and the Supabase client. Your React components, styles and Supabase database mostly stay as they are. The table maps each Vite piece to its Next.js replacement, following the Next.js guide for migrating from Vite and Supabase's server-side auth docs.
| In the Lovable app | In Next.js | Notes |
|---|---|---|
| index.html | app/layout.tsx (the root layout) | Head tags move into a metadata export |
| src/main.tsx | app/[[...slug]]/page.tsx plus one client component | The optional catch-all sends every URL to your existing App at first |
| React Router route list | Folders under app/, each with a page.tsx | Move one route at a time |
| vite.config.ts | next.config.mjs | output: 'export' while the app is still a single-page app |
| VITE_ variables read with import.meta.env | NEXT_PUBLIC_ variables read with process.env | Both are written into browser code at build time |
| Static image imports (a URL string) | Static image imports (an object: use .src) | Or point at the /public path directly |
| One browser Supabase client | @supabase/ssr browser and server clients | The session moves into cookies so server code can read it |
Step 1: How do you get the Lovable code ready to convert?
Connect Git sync or download the codebase, clone it, and create a branch for the conversion. Before changing anything, run npm install and npm run build on the untouched Vite project. If it doesn't build cleanly now, fix that first: converting a broken build only buries the original error under new ones, and you lose the clean baseline to compare against.
- In Lovable, connect Git sync to GitHub, or download the codebase as a .zip on a paid plan.
- Clone the repository and create a branch such as nextjs-conversion. Lovable keeps pushing to the default branch.
- Run npm install, then npm run build, and confirm the Vite build passes.
- Open package.json. If @tanstack/react-start is listed, the Vite steps below don't apply; see the FAQ on TanStack Start projects.
- List every route in your React Router setup and every VITE_ variable the code reads. Those two lists are your checklist for the rest of the job.
Related: Run a Lovable app locally · What breaks when you export a Lovable app
Step 2: How do you run the Lovable app on Next.js without breaking it?
Follow Next.js's official Vite migration in order and keep the app client-rendered at first. You add Next.js, turn index.html into a root layout, and route every URL through an optional catch-all page that loads your existing App component in the browser. Nothing is server-rendered yet, but the app builds and runs on Next.js, which is the safe checkpoint to commit.
- Install Next.js: npm install next@latest.
- Create next.config.mjs with output: 'export' and distDir: './dist', so the build still produces a static single-page app.
- Update tsconfig.json as the guide lists: add the next plugin, include next-env.d.ts, and set jsx to react-jsx with esModuleInterop, allowJs and incremental turned on.
- Create src/app/layout.tsx from index.html: keep the html and body tags, render {children} inside <div id="root">, and move the title and description into a metadata export.
- Create src/app/[[...slug]]/page.tsx that imports your global CSS, returns only the index route from generateStaticParams, and renders a client component which loads App with dynamic(() => import('../../App'), { ssr: false }).
- Change static image imports to use .src, and rename every VITE_ variable to NEXT_PUBLIC_ in your .env files and code.
- Replace the dev, build and start scripts with next dev, next build and next start, and add .next and next-env.d.ts to .gitignore.
- Run npm run dev and click through every route. When everything works, delete main.tsx, index.html, vite.config.ts, vite-env.d.ts and tsconfig.node.json, and uninstall Vite.
Step 3: How do you move React Router routes to the App Router?
Move one route at a time. Create the folder for a path under app/ with a page.tsx, move that screen into it, and the catch-all keeps serving every route you haven't moved yet. Start with the public pages you want indexed, because a page only renders on the server once it has its own App Router file with its own title and description.
In the App Router, layouts and pages are Server Components by default. Any component that uses state, effects, event handlers or browser APIs needs 'use client' at the top of its file. When one is missed, or code reads window while rendering, the build fails with 'window is not defined'. Keep the interactive parts in small client components and let the page around them render on the server.
| React Router (Lovable app) | Next.js App Router |
|---|---|
| <Route path="/" element={<Home />} /> | app/page.tsx |
| <Route path="/pricing" … /> | app/pricing/page.tsx |
| <Route path="/posts/:id" … /> | app/posts/[id]/page.tsx; params arrives as a Promise you await |
| A layout route that renders <Outlet /> | layout.tsx that renders {children} |
| <Route path="*" … /> (not found) | app/not-found.tsx |
| <Link to="/pricing"> | <Link href="/pricing"> from next/link |
| useNavigate() | useRouter() from next/navigation, then router.push() |
| useParams(), useLocation(), useSearchParams() | useParams(), usePathname(), useSearchParams() from next/navigation |
Step 4: How do you move Supabase auth to Next.js?
Keep the same Supabase project, so your data, users and RLS policies don't move. What changes is the client: Supabase's server-side auth guide uses the @supabase/ssr package, which keeps the session in cookies so server code can read it. You create a browser client for Client Components, a server client per request, and a Proxy file that refreshes the session.
Your RLS policies carry over unchanged, which makes this a good moment to check them: paste them into the free Lovable RLS policy checker before the new site goes live.
- Install the packages: npm install @supabase/supabase-js @supabase/ssr.
- Set NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY. The legacy anon key plays the publishable key's role on projects that still use it.
- Replace the single Supabase client with two: createBrowserClient for Client Components, and createServerClient, built for each request from that request's cookies, for Server Components, Server Actions and Route Handlers.
- Add proxy.ts (Next.js 16 and later; middleware.ts on Next.js 15 and earlier) that calls supabase.auth.getClaims() to refresh the session and returns the response carrying the refreshed cookies.
- Protect pages and data on the server with getClaims(), not getSession(). Supabase warns that getSession() reads the cookie without revalidating it.
- Add the new site's URLs to your Supabase Auth redirect settings before you test sign-in on them.
Step 5: How do you test and cut over without losing traffic?
Deploy the Next.js branch to a preview URL and test it as a user before touching DNS. Keep every URL path exactly as it was; a path that changes needs a 301 redirect, or the links and rankings pointing at it are lost. Leave the Lovable-hosted version running until the new one passes, so going back is only a DNS change.
- Open every old URL on the preview, directly and by refreshing, and confirm each one returns its page rather than a 404.
- Sign up, sign in, sign out, and reload a signed-in page to confirm the session survives.
- View the page source of your public pages: their headings and copy should be in the HTML itself, not only after JavaScript runs.
- Check the browser console and the host's build log for missing NEXT_PUBLIC_ values. They are fixed at build time, so redeploy after adding one.
- Point the domain at the new host, then update Supabase Auth's site URL and any webhook endpoints that still name the old domain.
Related: Move a Lovable app to Vercel: env vars, auth URLs and rollback · Migration order of operations
Can you convert a Lovable app to Next.js with an AI prompt?
Partly. An AI coding agent such as Cursor or Claude Code handles the mechanical steps well when you give it the order and the limits, and badly when you ask for the whole conversion at once. Give it one phase per prompt, make it build after each step, and forbid it from touching your database schema or migration files.
A first-phase prompt that works: “Convert this Lovable React + Vite app to Next.js (App Router) on the branch nextjs-conversion. Follow the official Next.js guide ‘How to migrate from Vite to Next.js’ exactly and stop when it ends: keep the app client-rendered through an optional catch-all page that loads App with ssr: false, rename every VITE_ variable to NEXT_PUBLIC_, and keep every URL path unchanged. Don't touch supabase/, drizzle/ or any SQL, and don't change what components do. Run the build after each step, fix only errors you caused, and list anything you couldn't convert.”
Then give it one prompt per route for Step 3, and do the Supabase auth step against Supabase's own guide, checking each file yourself. Auth is where a plausible-looking mistake costs you users.
When is it worth handing the conversion to a developer?
The job grows with the number of routes, the auth flows, Edge Functions and payments, and with how many URLs already earn search traffic. A marketing site with a handful of pages is a manageable do-it-yourself project. An app with sign-in, roles, Stripe webhooks and indexed pages is a migration, and the risk sits in auth, data and the cutover rather than in the code.
Our Lovable migration service covers the parts that break most often in a move like this: a pre-flight audit of env vars, secrets, auth and RLS; hosting rebuilt on Vercel, Cloudflare or Netlify; data and auth users moved to your own Supabase if you want that; and the domain cutover with sign-in, payments and logs verified. It's quoted after a free scoping call, and that call is the place to weigh a Next.js conversion against Lovable's own TanStack Start upgrade.
Frequently asked questions
Does Lovable use Next.js?
Will converting to Next.js improve my Lovable app's SEO?
Can I keep editing the app in Lovable after converting it to Next.js?
Will my Supabase data and users move when I convert?
How do I convert a TanStack Start Lovable project to Next.js?
What does 'window is not defined' mean after moving to Next.js?
Sources
- Lovable Docs — FAQ (one stack for every project; TanStack Start since 13 May 2026; React + Vite before; code export)
- Lovable Docs — upgrade to TanStack Start (eligibility, credits, reverting, browser-only libraries)
- Lovable Docs — deploying and hosting outside Lovable (how to tell the two stacks apart)
- Next.js Docs — migrating from Vite
- Next.js Docs — dynamic route segments (params is a Promise)
- Next.js Docs — Server and Client Components
- Next.js Docs — static exports (unsupported features)
- Next.js Docs — environment variables (NEXT_PUBLIC_ values are inlined at build time)
- Supabase Docs — creating a Supabase client for SSR (@supabase/ssr, Proxy, getClaims)
- Supabase Docs — API keys (publishable vs secret keys)
Talk to a senior engineer — not a salesperson.
Book a free 30-minute audit call. We'll diagnose what's wrong and tell you exactly what it costs to fix.