Lovable Setup & Debugger

Diagnostic Workflow

1. GET ERROR    → User provides error message or screenshot
2. ASK USER     → Request browser console info (see "What to Ask User" below)
3. DIFF CHECK   → Compare user files to working examples (see references/working-examples.md)
4. CATEGORIZE   → Match to error pattern below (or case study)
5. FIX          → Apply corresponding solution
6. VERIFY       → Build locally, push, refresh Lovable

For complex issues:

• Read references/working-examples.md for complete working file examples to diff against
• Read references/case-studies.md for real debugging examples with symptoms and fixes

What to Ask User

When user reports "white screen" or "not loading", ask them to check browser DevTools:

1. Console tab: Any JavaScript errors?
2. Network tab: Any requests with non-200 status codes?
   • 404 = Missing file
   • 500 = Server/build error
   • 504 = Dependency timeout (needs optimizeDeps fix)

This info immediately narrows down the issue category.

Error Categories & Fixes

Supabase Types Out of Sync

Error: TypeScript errors referencing missing tables, RPC functions, or columns

Cause: types.ts not regenerated after database migrations

Fix:

npx supabase gen types typescript --project-id iryqgmjauybluwnqhxbg > apps/raamattu-nyt/src/integrations/supabase/types.ts
git add apps/raamattu-nyt/src/integrations/supabase/types.ts
git commit -m "chore: Regenerate Supabase types"
git push

Workaround (when regeneration not possible):

// biome-ignore lint/suspicious/noExplicitAny: RPC not in generated types
const { data, error } = await supabase.rpc("new_function" as any, { p_id: id });

See also: /supabase-migration-writer skill for migration best practices.

White Screen / Dynamic Import Failure

Error: Failed to fetch dynamically imported module: .../AppEntry.tsx

Diagnosis:

# Check TypeScript
npm run typecheck --workspace=apps/raamattu-nyt

# Check build
npm run build --workspace=apps/raamattu-nyt

Common causes & fixes:

AppEntry.tsx Pattern (Lovable's entry point):

// apps/raamattu-nyt/src/AppEntry.tsx
import App from "./App";
export default App;

504 Gateway Timeout on Dependencies

Error: GET .../node_modules/.vite/deps/[package].js 504 (Gateway Timeout)

Cause: Lovable server timeout during dependency pre-bundling.

Fix: Add problematic dependency to optimizeDeps.include in vite.config.ts:

optimizeDeps: {
  include: [
    "react",
    "react-dom",
    "framer-motion",  // Add timeout-causing package here
  ],
}

Package with Broken Exports (@tiptap/pm)

Error: Failed to resolve entry for package "@tiptap/pm". Missing "." specifier in package

Cause: Some packages (notably @tiptap/pm) have incorrect exports field in their package.json that Vite cannot resolve during pre-bundling.

Fix: Add to optimizeDeps.exclude (NOT include):

optimizeDeps: {
  include: [
    "@tiptap/react",
    "@tiptap/starter-kit",
    // Do NOT include @tiptap/pm here
  ],
  exclude: ["@tiptap/pm"],  // Exclude packages with broken exports
}

Why: Excluding tells Vite to skip pre-bundling for this package, allowing it to be resolved differently at runtime.

Known packages with this issue: @tiptap/pm

Missing Script

Error: npm error Missing script: "build:dev"

Fix: Add delegation scripts to root package.json:

{
  "scripts": {
    "dev": "npm run dev --workspace=apps/[app-name]",
    "build": "npm run build --workspace=apps/[app-name]",
    "build:dev": "npm run build:dev --workspace=apps/[app-name]"
  }
}

PostCSS/Tailwind Resolution

Error: [plugin:vite:css] [postcss] Cannot find package 'postcss' or Cannot find module 'tailwindcss'

Cause: Build toolchain dependency not available in Lovable preview (installs only production deps).

Quick fix:

# Add to root package.json dependencies (not devDependencies)
npm install --save postcss autoprefixer tailwindcss
git add package.json package-lock.json
git push

Full playbook: See references/postcss-white-screen-playbook.md for complete triage checklist covering:

• Dependency placement verification
• Lockfile consistency
• PostCSS config conflicts (root vs app-level)
• Tailwind v4 plugin requirements
• Prevention guardrails

Workspace Package Resolution

Error: Rollup failed to resolve import "react/jsx-runtime"

Fix: Update vite.config.ts:

optimizeDeps: {
  include: ["react", "react-dom", "react/jsx-runtime"],
},
build: {
  commonjsOptions: {
    include: [/packages\/.*/, /node_modules/],
  },
},

Lock File Out of Sync

Error: npm ci can only install packages when package.json and package-lock.json are in sync

Fix:

rm package-lock.json
npm install
git add package-lock.json
git commit -m "Refresh package-lock.json"
git push

Schema Query Errors

Error: Could not find the table 'public.table_name' in the schema cache

Fix: Add .schema() before .from():

// Before (wrong - queries public schema)
const { data } = await supabase.from("table_name").select("*");

// After (correct - queries specific schema)
const { data } = await (supabase as any)
  .schema("bible_schema")
  .from("table_name")
  .select("*");

Quick Diagnostic Commands

# 1. Check if code compiles
npm run typecheck --workspace=apps/raamattu-nyt

# 2. Check if build works
npm run build --workspace=apps/raamattu-nyt

# 3. Check lock file sync
npm ci --dry-run

# 4. Check workspace structure
npm ls --depth=0

# 5. Find missing dependencies
npm ls 2>&1 | grep -E "missing|extraneous"

Vite Config Template

Complete vite.config.ts for Lovable monorepo:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import path from "path";
import { componentTagger } from "lovable-tagger";

export default defineConfig(({ mode }) => ({
  plugins: [react(), mode === "development" && componentTagger()].filter(Boolean),
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
      "@ui": path.resolve(__dirname, "../../packages/ui/src"),
      "@shared-auth": path.resolve(__dirname, "../../packages/shared-auth/src"),
    },
  },
  optimizeDeps: {
    include: [
      "react",
      "react-dom",
      "react/jsx-runtime",
      "framer-motion",
      // Add any packages that cause 504 timeouts
    ],
  },
  build: {
    commonjsOptions: {
      include: [/packages\/.*/, /node_modules/],
    },
  },
  server: {
    host: "0.0.0.0",
    port: 5173,
  },
}));

Test Mock Updates

When adding .schema() calls, update test mocks:

// Mock Supabase with schema() support
vi.mock("@/integrations/supabase/client", () => ({
  supabase: {
    schema: (_schemaName: string) => ({
      from: (table: string) => ({
        select: () => ({ or: () => ({ maybeSingle: () => mockData }) }),
        upsert: () => Promise.resolve({ error: null }),
      }),
    }),
  },
}));

Lovable-Specific Notes

• Lovable uses AppEntry.tsx as dynamic import entry point
• Editor runtime: /projects/... uses dynamic ESM imports
• Preview: id-preview--*.lovable.app is built bundle
• Dependencies must be in root package.json for Lovable to install them
• Use "Rebuild" in Lovable UI to clear cache
• 504 errors = Lovable infrastructure issue, retry or add to optimizeDeps

Pre-Push Checklist

Before pushing, always run:

npm ci --dry-run

This catches lockfile drift which is the #1 cause of Lovable white screens.

Health Check Page

A /health page exists (src/main.tsx) for diagnosing white screens:

Use this to quickly distinguish between:

1. React crash (health shows ✅) → Check console for JS errors, likely code bug
2. Build/serve failure (health doesn't load) → Check lockfile, deps, PostCSS

Reference Files

• Docs/16-DEBUG-LOVABLE-WHITE.md - Comprehensive white screen playbook (project-level docs):

  • Golden rule: white screen ≠ UI bug
  • Root causes ranked by frequency
  • Step-by-step fix checklist
  • Prevention strategies (CI guardrails)
  • Runtime error logging architecture (globalErrorLogger, DebugErrorOverlay)
  • /health page diagnostics

• references/postcss-white-screen-playbook.md - Complete triage for "Cannot find package 'postcss'" errors:

  • Root cause analysis (dependency placement, Tailwind v4, config conflicts)
  • Step-by-step verification checklist
  • Quick fix commands
  • Prevention guardrails (CI checks, single config rule)
  • AI agent prompt for automated diagnosis

• references/working-examples.md - Complete working configuration files for diffing:

  • AppEntry.tsx (correct vs incorrect patterns)
  • vite.config.ts (full working template)
  • package.json (root and app versions)
  • tsconfig.json (paths configuration)
  • postcss.config.js (correct location)
  • Diff checklist for quick comparison

• references/case-studies.md - Real debugging sessions (10 case studies):

  • Case 1: 504 Gateway Timeout → optimizeDeps fix
  • Case 2: AppEntry.tsx dynamic import failure → export pattern fix
  • Case 3: Schema query error → .schema() fix
  • Case 4: Package lock out of sync → regenerate lock file
  • Case 5: Vite root misconfigured → remove custom root
  • Case 6: Security headers blocking imports → conditional headers
  • Case 7: Missing error boundary → silent crash, add boundary
  • Case 8: Dependency in workspace only → move to root
  • Case 9: Incorrect base path → conditional base config
  • Case 10: Service worker caching old chunk → disable SW in dev
  • User Debugging Guide: How users can help diagnose issues

Quick Pattern Matching