Lovable app shows a blank white screen? The usual cause and the fix

Your app works inside Lovable. Then you deploy it somewhere else, or a collaborator clones it, and all anyone gets is a pure white page. The build passed with zero errors. Nothing in any log explains it. This is the single most common failure I see in Lovable and Bolt apps, and it almost always has the same cause.

The symptom

• npm install and npm run build both succeed with no errors
• The deployed site (or local npm run dev) shows a completely blank white page
• There is no error message on screen, not even a broken layout, just nothing
• It works fine inside Lovable itself, and often on the original owner's deployment

The cause: your app crashes before React starts

Lovable apps typically use Supabase, and the generated code usually contains a file like src/lib/supabase.ts or src/integrations/supabase/client.ts that reads two environment variables:

const supabaseUrl = import.meta.env.VITE_SUPABASE_URL;
const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY;

if (!supabaseUrl || !supabaseAnonKey) {
  throw new Error("supabaseUrl is required.");
}

Inside Lovable those variables are always injected, so this code never fails where the app was written. But Vite happily builds with the variables missing, it just inlines undefined. When someone opens the built app without them, the throw fires while the JavaScript bundle is still loading, before React mounts anything. Even if the app has an error boundary, it does not exist yet, so nothing can catch the crash. The page stays white.

Most generated repos also ship no .env.example and no setup docs, so every fresh clone and every new deployment hits this wall with no clue why.

Confirm it in 30 seconds

Open the blank page in Chrome, press F12 to open DevTools, and look at the Console tab. If this is your problem you will see a red uncaught error mentioning supabaseUrl is required, Missing Supabase, or similar, thrown from a file with supabase in the name.

The quick fix

Set the two environment variables wherever the app runs:

• Locally: create a file named .env in the project root with VITE_SUPABASE_URL=... and VITE_SUPABASE_ANON_KEY=.... Both values are in your Supabase dashboard under Project Settings, then API.
• Vercel or Netlify: add the same two variables in the project's environment settings, then redeploy. Vite only reads them at build time, so a redeploy is required.

The real fix

The quick fix gets you unblocked, but the app is still a landmine for the next person who clones or deploys it. The durable fix is to stop crashing at import time:

• In the supabase client file, replace the throw with an exported error value, and create the client with harmless placeholder values so the module always loads.
• In src/main.tsx, check that error value before mounting. If configuration is missing, render a small setup screen that says exactly which two variables to set and where to find them. Otherwise mount the app normally.
• Add a .env.example file documenting both variables.

I made exactly this fix to a real Lovable campus delivery app that white-screened on every fresh clone: 3 files, 34 lines. Verified in a headless browser: before the fix the page rendered 0 characters; after it, an unconfigured clone renders a setup screen and a configured one renders the full app, pixel-identical to the production site. The change is public: see the pull request.

Still white after setting the variables?

Then you are probably in a different failure class: a routing basename mismatch, a crashed top-level component, or a build that silently outputs to the wrong directory. Those need the console error and the repo to diagnose.