Fixing blank screen after exporting and deploying a V0 app

Why V0 exports show a blank screen after deployment

A blank screen means the HTML document loaded but JavaScript failed to render the application. This is different from a build error, which stops deployment entirely. V0 code runs correctly in the V0 preview sandbox because it has pre-configured environment variables, module resolution, and a permissive runtime. When you export and deploy to Vercel or another platform, several things can go wrong: environment variables from the V0 Vars panel are not automatically transferred to Vercel, Client Components may access localStorage or window during server-side rendering, the @/ import alias may not resolve in the exported project, and shadcn/ui components may reference registry entries that do not exist locally.

• Environment variables from V0 Vars panel not set in the deployment platform's environment settings
• Client Component accesses localStorage or window during server-side rendering, throwing ReferenceError
• The @/ import path alias is not configured in the exported project's tsconfig.json
• shadcn/ui components reference registry URLs that fail to resolve outside V0's sandbox
• Missing static assets (images, fonts) that prevent the page from fully rendering

Error messages you might see

Before you start

• A V0 project exported and deployed to Vercel or another hosting platform
• Access to the browser DevTools console on the deployed URL
• Access to the deployment platform's build and runtime logs

How to fix it

// Blank white screen — no visible error to the user

// Browser Console shows:
// ReferenceError: localStorage is not defined
// at ThemeProvider (theme-provider.tsx:12)
// Now you know the exact file and line to fix

// V0 Vars panel has:
// NEXT_PUBLIC_SUPABASE_URL=https://abc.supabase.co
// NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
// But Vercel project has NO environment variables set

// Vercel Dashboard → Settings → Environment Variables:
// NEXT_PUBLIC_SUPABASE_URL = https://abc.supabase.co
// NEXT_PUBLIC_SUPABASE_ANON_KEY = eyJ...
// Redeploy after adding variables

"use client";
import { useState } from "react";
export function ThemeProvider({ children }: { children: React.ReactNode }) {
  // Crashes during SSR — localStorage not available
  const [theme, setTheme] = useState(
    localStorage.getItem("theme") || "light"
  );
  return <div className={theme}>{children}</div>;
}

"use client";
import { useState, useEffect } from "react";
export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setTheme] = useState("light");
  useEffect(() => {
    const saved = localStorage.getItem("theme");
    if (saved) setTheme(saved);
  }, []);
  return <div className={theme}>{children}</div>;
}

{
  "compilerOptions": {
    "strict": true
  }
}

{
  "compilerOptions": {
    "strict": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}

Complete code example

1"use client";
2
3import { useEffect, useState, type ReactNode } from "react";
4
5interface SafeHydrationProps {
6  children: ReactNode;
7  fallback?: ReactNode;
8}
9
10/**
11 * Wraps components that access browser-only APIs.
12 * Shows fallback during SSR and initial hydration,
13 * then renders children after the component mounts.
14 */
15export function SafeHydration({
16  children,
17  fallback = null,
18}: SafeHydrationProps) {
19  const [mounted, setMounted] = useState(false);
20
21  useEffect(() => {
22    setMounted(true);
23  }, []);
24
25  if (!mounted) {
26    return <>{fallback}</>;
27  }
28
29  return <>{children}</>;
30}

Best practices to prevent this

• Always check the browser console first when diagnosing a blank screen — it reveals the exact error
• Set all environment variables on Vercel immediately after connecting the GitHub repository, before the first deploy
• Never access localStorage, window, or document directly in component state initializers — use useEffect instead
• Configure the @/ import alias in tsconfig.json immediately after exporting V0 code
• Test the exported project locally before deploying to catch SSR errors early
• Use the SafeHydration wrapper component for any UI that depends on browser-only APIs
• For persistent blank screen issues after export, RapidDev can audit and fix all SSR compatibility issues systematically

Still stuck?

Copy one of these prompts to get a personalized, step-by-step explanation.

Related error patterns

Explore related guides

Guides from other topics that help with this issue