Lovable

Lovable Integration Skill

This skill enables Claude Code to work effectively with Lovable.dev projects while respecting Lovable's deployment requirements.

When to Use This Skill

Activate when:

• User mentions "Lovable" or "lovable.dev"
• Project has supabase/ directory with Edge Functions
• User asks to deploy edge functions
• User creates database migrations
• User asks about Lovable Cloud or backend deployment
• Project appears to be a Lovable project (React + Supabase structure)

Project Architecture Types

Lovable supports two architectures. Always detect which one you're working with before giving advice.

Detecting Architecture

Check the root directory of the user's project:

• app.config.ts present → TanStack Start (new, SSR — post-April 2026)
• vite.config.ts present → Vite SPA (legacy, CSR — pre-April 2026)

Both are fully supported. Old projects remain on Vite and receive no forced migration.

---

Vite SPA Architecture (Legacy)

Projects created before April 2026. Client-side rendering only.

What Syncs Automatically (Vite SPA)

✅ Edit freely and push to main:

• src/ - All React components, pages, hooks, utils
• public/ - Static assets
• Config files - vite.config.ts, tailwind.config.js, tsconfig.json
• package.json - Dependencies
• supabase/functions/*/index.ts - Edge Function code (not deployment)
• supabase/migrations/*.sql - Migration files (not application)

What Requires Lovable Deployment (Vite SPA)

⚠️ After editing, provide Lovable prompt:

---

TanStack Start Architecture (New Projects)

Projects created after April 2026. Full server-side rendering (SSR) via TanStack Start.

Key Differences from Vite SPA

• Routes are file-based in app/routes/ (not React Router in src/App.tsx)
• Config file is app.config.ts (not vite.config.ts)
• Server functions (createServerFn) let server-side logic live directly in component files — no edge function needed for simple server logic
• Files named *.server.ts are server-only and never sent to the browser
• Pages are rendered as complete HTML on the server before reaching the browser

What Syncs Automatically (TanStack Start)

✅ Edit freely and push to main:

• app/ - All routes, components, server functions, layouts
• app/routes/ - File-based route pages
• public/ - Static assets
• app.config.ts, tailwind.config.js, tsconfig.json - Config files
• package.json - Dependencies
• app/**/*.server.ts - TanStack server functions (auto-deploys, no Lovable prompt needed)
• supabase/functions/*/index.ts - Supabase Edge Function code (not deployment)
• supabase/migrations/*.sql - Migration files (not application)

What Requires Lovable Deployment (TanStack Start)

⚠️ After editing, provide Lovable prompt:

Note: TanStack server functions (createServerFn) are not Supabase Edge Functions. They live in app/ and deploy automatically via GitHub sync — no Lovable prompt needed. Only supabase/functions/ requires manual deployment.

TanStack Start File Structure

project/
├── app/                          # ✅ Safe - auto-syncs
│   ├── routes/                   # File-based routing
│   │   ├── __root.tsx            # Root layout
│   │   ├── index.tsx             # Home page (/)
│   │   └── [route].tsx           # Other pages
│   ├── components/               # Shared UI components
│   ├── lib/                      # Utilities and helpers
│   └── *.server.ts               # ✅ Server functions (auto-deploy)
├── app.config.ts                 # TanStack Start config
├── public/                       # Static assets
├── supabase/
│   ├── functions/                # ✅ Edit code, ⚠️ needs deploy
│   └── migrations/               # ✅ Create files, ⚠️ needs apply
└── CLAUDE.md                     # Project context

---

Core Concept (Both Architectures)

Lovable uses two-way GitHub sync on the main branch only:

• Frontend and server-side code (including TanStack server functions) sync automatically
• Supabase Edge Functions and database migrations require Lovable prompts after code changes

Response Format

When backend deployment is needed, always output:

📋 **LOVABLE PROMPT:**
> "[exact prompt to copy-paste]"

For destructive operations, add:

⚠️ **Warning**: [explanation of risk]

File Structure Reference

Vite SPA (Legacy — vite.config.ts present)

project/
├── src/                          # ✅ Safe - auto-syncs
│   ├── components/
│   ├── pages/
│   ├── hooks/
│   ├── lib/
│   └── integrations/supabase/
│       ├── client.ts             # ⚠️ Has Supabase URLs
│       └── types.ts
├── supabase/
│   ├── functions/                # ✅ Edit code, ⚠️ needs deploy
│   │   └── [function-name]/
│   │       └── index.ts
│   ├── migrations/               # ✅ Create files, ⚠️ needs apply
│   │   └── YYYYMMDDHHMMSS_*.sql
│   └── config.toml               # ⚠️ Lovable Cloud manages
├── .env                          # Local only - Lovable ignores
└── CLAUDE.md                     # Project context

TanStack Start (New — app.config.ts present)

project/
├── app/                          # ✅ Safe - auto-syncs
│   ├── routes/                   # File-based routing
│   │   ├── __root.tsx            # Root layout
│   │   ├── index.tsx             # Home route (/)
│   │   └── [name].tsx            # Named routes
│   ├── components/               # Shared components
│   ├── lib/                      # Utilities
│   ├── integrations/supabase/    # Supabase client + types
│   └── *.server.ts               # ✅ Server functions (auto-deploy, no prompt needed)
├── app.config.ts                 # TanStack Start config
├── public/                       # Static assets
├── supabase/
│   ├── functions/                # ✅ Edit code, ⚠️ needs deploy via Lovable
│   │   └── [function-name]/
│   │       └── index.ts
│   ├── migrations/               # ✅ Create files, ⚠️ needs apply via Lovable
│   │   └── YYYYMMDDHHMMSS_*.sql
│   └── config.toml               # ⚠️ Lovable Cloud manages
├── .env                          # Local only - Lovable ignores
└── CLAUDE.md                     # Project context

Backend Types

Lovable Cloud

• Backend managed entirely by Lovable
• No Supabase dashboard access
• All operations via Lovable prompts
• Secrets in Cloud → Secrets UI

Own Supabase

• Direct Supabase dashboard access
• Can use Supabase CLI: supabase functions deploy
• More flexibility but manual setup

Quick Prompts Reference

Edge Functions

"Deploy all edge functions"
"Deploy the send-email edge function"
"Create an edge function called [name] that [description]"
"Show logs for [name] edge function"
"The [name] edge function returns [error]. Fix it"

Database

"Create a [name] table with columns: id (uuid), name (text), created_at (timestamp)"
"Add a [column] column of type [type] to [table]"
"Add foreign key from [table1].[col] to [table2].id"
"Apply pending Supabase migrations"

RLS Policies

"Enable RLS on [table]"
"Add RLS policy on [table] allowing authenticated users to read all rows"
"Add RLS policy on [table] allowing users to only access their own rows"

Storage

"Create a public storage bucket called [name]"
"Create a private storage bucket called [name]"
"Allow authenticated users to upload to [bucket]"

Auth

"Enable Google authentication"
"Enable GitHub authentication"
"When user signs up, create row in profiles table"

Branch Rules

• Only `main` syncs with Lovable
• Feature branches don't deploy until merged
• Lovable syncs within 1-2 minutes of push

Yolo Mode - Automated Deployments (Beta)

When yolo_mode: on in CLAUDE.md, deployments are automated via browser automation:

How It Works

Instead of showing manual prompts, the yolo skill (/skills/yolo/SKILL.md) takes over: 1. Automatically navigates to Lovable.dev 2. Submits deployment prompts 3. Monitors for success/failure 4. Runs verification tests (if enabled) 5. Reports deployment summary

When Yolo Mode Activates

• During /lovable:deploy-edge command
• During /lovable:apply-migration command
• When yolo_mode: on in CLAUDE.md

Configure Yolo Mode

/lovable:yolo on               # Enable with testing
/lovable:yolo on --no-testing  # Enable without testing
/lovable:yolo on --debug       # Enable with verbose logs
/lovable:yolo off              # Disable

Beta Status

⚠️ Yolo mode is in beta:

• Requires Claude in Chrome extension
• May have bugs or UI compatibility issues
• Always has manual fallback
• See /skills/yolo/SKILL.md for details

Debugging Checklist

1. Frontend not updating?

• On main branch?
• Changes pushed?
• Wait 1-2 min

2. Edge Function not working?

• Deployed via Lovable (or yolo mode)?
• Secrets set in Cloud UI?
• Check logs in Lovable

3. Database query failing?

• Migration applied (via Lovable or yolo mode)?
• RLS policies correct?
• Table exists?

4. Yolo mode not working?

• Check yolo_mode: on in CLAUDE.md
• Chrome extension installed?
• Logged into Lovable?
• See yolo skill for troubleshooting

CLAUDE.md - Lovable Project Context

This file is generated by /init-lovable. Edit to match your project.

Project Overview

• Name: [PROJECT_NAME]
• Production URL: [PRODUCTION_URL]
• Lovable Project URL: [LOVABLE_PROJECT_URL]
• GitHub: [GITHUB_URL]
• Backend: [Lovable Cloud / Own Supabase]
• Supabase Ref: [SUPABASE_REF] (if own Supabase)
• Architecture: [Vite SPA (CSR) / TanStack Start (SSR)]

Project Structure Map

Quick navigation guide - run /lovable:map --update to refresh

<!-- FOR VITE SPA PROJECTS (vite.config.ts): use this layout -->

Directory Layout

src/
├── components/    # [COMPONENT_PATTERN] ([COMPONENT_COUNT] components)
│   └── ui/        # shadcn/ui primitives
├── pages/         # Route pages ([PAGE_COUNT] pages)
├── hooks/         # Custom React hooks ([HOOK_COUNT] hooks)
├── lib/           # Utilities and helpers
├── integrations/  # External integrations
│   └── supabase/  # Supabase client and generated types
[ADDITIONAL_DIRS]

supabase/
├── functions/     # Supabase Edge Functions ([FUNCTION_COUNT]) — needs deploy
└── migrations/    # Database migrations ([MIGRATION_COUNT] migrations)

Key Files

[ADDITIONAL_KEY_FILES]

Patterns

• Components: [COMPONENT_PATTERN_DESC]
• State: [STATE_MANAGEMENT]
• Data Flow: Pages → Hooks → Supabase Client → Edge Functions

Quick Lookup

<!-- FOR TANSTACK START PROJECTS (app.config.ts): replace above with this layout --> <!--

Directory Layout

app/
├── routes/        # File-based routes ([ROUTE_COUNT] routes)
│   ├── __root.tsx # Root layout
│   └── *.tsx      # Page routes (filename = URL path)
├── components/    # [COMPONENT_PATTERN] ([COMPONENT_COUNT] components)
│   └── ui/        # shadcn/ui primitives
├── lib/           # Utilities and helpers
├── integrations/  # External integrations
│   └── supabase/  # Supabase client and generated types
[ADDITIONAL_DIRS]

supabase/
├── functions/     # Supabase Edge Functions ([FUNCTION_COUNT]) — needs deploy
└── migrations/    # Database migrations ([MIGRATION_COUNT] migrations)

Key Files

[ADDITIONAL_KEY_FILES]

Patterns

• Architecture: SSR — HTML rendered server-side before browser
• Routing: File-based (app/routes/*.tsx = URL routes)
• Server functions: *.server.ts files auto-deploy — no Lovable prompt needed
• Components: [COMPONENT_PATTERN_DESC]
• State: [STATE_MANAGEMENT]
• Data Flow: Routes (loaders) → Supabase Client → Edge Functions

Quick Lookup

-->

*Map generated: [MAP_TIMESTAMP]*

---

## 🚨 IMPORTANT: Always Commit and Push to GitHub

**This is critical:** Lovable syncs changes FROM GitHub. If you don't commit and push your changes, they won't sync back to Lovable!

### ✅ ALWAYS do this:
1. Make changes to your code
2. **Commit changes**: `git add . && git commit -m "description"`
3. **Push to main**: `git push origin main`
4. Wait 1-2 minutes for Lovable to sync
5. Verify changes in Lovable

**Without pushing to GitHub, your changes are stuck in Claude Code and won't reach Lovable or your team.**

### 🔄 GitHub → Lovable Sync Flow

Your changes in Claude Code ↓ git add . && git commit -m "Your message" ↓ git push origin main ← REQUIRED! ↓ Lovable automatically syncs (1-2 minutes) ↓ Changes live in Lovable

---

## Workflow Rules

<!-- If Architecture: Vite SPA, use these rules -->
### ✅ Safe to edit and push to `main`:
- All files in `src/` (components, pages, hooks, utils)
- Config files (`vite.config.ts`, `tailwind.config.js`)
- Package.json dependencies
- Edge Function **code** in `supabase/functions/`
- Migration **files** in `supabase/migrations/`

### ⚠️ After editing, provide Lovable prompt:
- **Edge Functions**: `"Deploy the [name] edge function"`
- **Migrations**: `"Apply pending Supabase migrations"`

### ❌ Must go through Lovable:
- Create/modify database tables
- Set up RLS policies
- Add secrets (Cloud → Secrets UI)
- Create storage buckets
- Deploy Supabase Edge Functions

<!-- If Architecture: TanStack Start, replace the above with:

### ✅ Safe to edit and push to `main`:
- All files in `app/` (routes, components, lib, integrations)
- TanStack server functions (`app/**/*.server.ts`) — auto-deploy via GitHub, no prompt needed
- Config files (`app.config.ts`, `tailwind.config.js`)
- Package.json dependencies
- Supabase Edge Function **code** in `supabase/functions/`
- Migration **files** in `supabase/migrations/`

### ⚠️ After editing, provide Lovable prompt:
- **Supabase Edge Functions**: `"Deploy the [name] edge function"`
- **Migrations**: `"Apply pending Supabase migrations"`

> Note: TanStack server functions (`*.server.ts` in `app/`) are NOT Supabase Edge Functions.
> They deploy automatically with the rest of your app — no Lovable prompt needed.

### ❌ Must go through Lovable:
- Create/modify database tables
- Set up RLS policies
- Add secrets (Cloud → Secrets UI)
- Create storage buckets
- Deploy Supabase Edge Functions
-->

## Secrets

| Name | Purpose | Status | Used In |
|------|---------|--------|---------|
| OPENAI_API_KEY | AI features | ⚠️ Not configured | chat-completion |
| STRIPE_SECRET_KEY | Payments | ⚠️ Not configured | process-payment |
| RESEND_API_KEY | Emails | ✅ In Lovable Cloud | send-email, send-welcome |

**Legend:**
- ✅ In Lovable Cloud - Secret already configured
- ⚠️ Not configured - Needs setup in Cloud → Secrets

**To add secrets:**
1. Go to Cloud → Secrets in Lovable
2. Click "Add secret"
3. Enter name and value
4. Run: `"Redeploy edge functions to pick up new secrets"`

## Edge Functions

| Function | Purpose | Required Secrets | Status |
|----------|---------|------------------|--------|
| send-email | Send transactional emails | RESEND_API_KEY | ✅ Secret configured |
| process-payment | Handle Stripe webhooks | STRIPE_SECRET_KEY | ⚠️ Secret not configured |

**Warning:** Functions marked with ⚠️ will fail until secrets are added in Cloud → Secrets.

## Database Tables

| Table | Purpose |
|-------|---------|
| profiles | User profiles |
| projects | User projects |

## Project Conventions

- Use shadcn/ui components
- Follow existing naming patterns
- Don't modify auth logic without discussion

## Yolo Mode Configuration (Beta)

> ⚠️ Beta feature - auto-submits Lovable prompts via MCP or browser automation

- **Status**: [on / off]
- **Deployment Method**: [auto / mcp / browser]  # auto tries MCP first, then browser
- **Auto-Deploy**: [on / off]  # Auto-deploy to Lovable after git push (no manual command needed)
- **Deployment Testing**: [on / off]  # Run verification tests after Lovable deployments
- **Auto-run Tests**: [on / off]  # Run project tests after every git push
- **Debug Mode**: [on / off]  # Verbose logging of automation steps
- **Last Updated**: [timestamp]
- **Operations Covered**:
  - Automatic deployment detection after git push
  - Edge function deployment with verification
  - Migration application with verification
  - Automated code testing after every git push

**Configure:** Run `/lovable:yolo on/off [--mcp|--browser|--auto] [--testing|--no-testing] [--debug]`
**Connect MCP:** Run `/lovable:connect-mcp` for faster, more reliable automation

**Deployment methods:**
- **MCP** (recommended): Sends prompts via Lovable API - faster, no Chrome extension needed
  - Setup: `/lovable:connect-mcp`
- **Browser** (fallback): Navigates to Lovable UI - requires Chrome extension

**How it works:**
- **Deployment Method: auto** - Tries MCP first, falls back to browser if not connected
- **Deployment Method: mcp** - Uses Lovable MCP only (best performance)
- **Deployment Method: browser** - Uses browser automation (legacy)
- Auto-Deploy: Automatically deploys backend changes after git push - no need to run `/deploy-edge`
- Deployment testing verifies deployments (3 levels: basic, console errors, functional)
- Always has manual fallback if automation fails

**Auto-Deploy Flow:**

git push origin main → Claude detects backend changes → Automatic deployment starts (MCP or browser)

## Preview Testing Configuration

> 🧪 Beta - tests the app in Lovable Preview mode via browser automation.
> Test workspace: `.claude/lovable-claude/test/` (plans, profiles, results).

- **Status**: [on / off]
- **Preview URL**: [https://preview--app-name.lovable.app - WITHOUT token]
- **Access Method**: [token / browser-login]
- **Token Captured**: [date] (valid ~7 days - renew with `/lovable:test-init --refresh-token`)
- **Test After Implementation**: [on / off]  # run affected test plans after each feature
- **Test After Deploy**: [off / smoke / all]  # run after yolo auto-deploy
- **Last Test Sync**: [commit hash]

**Commands:**
- `/lovable:test-run [TP-NNN | --all | --changed | --smoke]` - run tests in Preview
- `/lovable:test-sync` - update test plans for new/changed features
- `/lovable:test-init` - re-run setup wizard / refresh token

**Maintenance rule:** when implementing a new feature, also add/update unit tests and
test plans covering it (or run `/lovable:test-sync`). Keep plans' `covers:` paths accurate.

> 🔐 The preview token is stored ONLY in `.claude/lovable-claude/test/preview-token.local`
> (gitignored). Never write it to this file or commit it.

## Quick Prompts Reference

| Task | Lovable Prompt |
|------|----------------|
| Deploy all functions | `"Deploy all edge functions"` |
| Deploy specific | `"Deploy the [name] edge function"` |
| Apply migrations | `"Apply pending Supabase migrations"` |
| Check logs | `"Show logs for [name] edge function"` |
| Fix function | `"The [name] edge function returns [error]. Fix it"` |
| Create table | `"Create a [name] table with columns: [list]"` |
| Add RLS | `"Enable RLS on [table] allowing [who] to [what]"` |
| Add secret | ⚠️ Manual: Cloud → Secrets |

## Branch Rules

- **Only `main` syncs** with Lovable
- Feature branches don't deploy until merged
- Lovable syncs within 1-2 minutes of push

---
*Template from lovable-integration plugin. Run `/init-lovable` to customize.*

Codebase Map Generation Reference

This reference defines how to scan and generate a Project Structure Map for Lovable projects.

Purpose

The codebase map helps Claude navigate user projects faster by providing:

• Directory structure with purposes
• Key files and their roles
• Component organization patterns
• Data flow overview

Target: ~60 lines, optimized for token efficiency while remaining useful.

---

Scanning Algorithm

Step 0: Detect Project Architecture

Before scanning, identify which architecture the project uses:

Record the architecture type — it affects which directories to scan and what to document.

Step 1: Scan Directory Structure

Vite SPA Projects (vite.config.ts)

Scan these directories in order:

1. src/                    # Main source code
   ├── components/         # UI components
   ├── pages/              # Route pages
   ├── hooks/              # Custom React hooks
   ├── lib/                # Utilities and helpers
   ├── utils/              # Alternative utilities location
   ├── services/           # API services
   ├── contexts/           # React contexts
   ├── stores/             # State management (zustand, etc.)
   ├── types/              # TypeScript definitions
   ├── integrations/       # External service integrations
   │   └── supabase/       # Supabase client and types
   └── assets/             # Static assets

2. supabase/               # Backend
   ├── functions/          # Supabase Edge Functions
   └── migrations/         # Database migrations

3. public/                 # Static files

4. Root config files       # vite.config.ts, tailwind.config, etc.

TanStack Start Projects (app.config.ts)

Scan these directories in order:

1. app/                    # Main source code (replaces src/)
   ├── routes/             # File-based route pages
   ├── components/         # UI components
   ├── lib/                # Utilities and helpers
   ├── utils/              # Alternative utilities location
   ├── services/           # API services
   ├── contexts/           # React contexts
   ├── stores/             # State management
   ├── types/              # TypeScript definitions
   ├── integrations/       # External service integrations
   │   └── supabase/       # Supabase client and types
   └── *.server.ts         # TanStack server functions (auto-deploy)

2. supabase/               # Backend
   ├── functions/          # Supabase Edge Functions (need deployment)
   └── migrations/         # Database migrations

3. public/                 # Static files

4. Root config files       # app.config.ts, tailwind.config, etc.

Step 2: Detect Component Organization Pattern

Check src/components/ structure:

Flat Pattern (all components at same level):

components/
├── Button.tsx
├── Card.tsx
├── Modal.tsx
└── ...

Feature-Based Pattern (grouped by feature):

components/
├── auth/
│   ├── LoginForm.tsx
│   └── SignupForm.tsx
├── dashboard/
│   ├── StatsCard.tsx
│   └── ActivityFeed.tsx
└── ui/                    # shadcn/ui primitives

Atomic Pattern (atoms/molecules/organisms):

components/
├── atoms/
├── molecules/
└── organisms/

Step 3: Identify Key Files

Scan for these important files based on architecture:

Vite SPA Key Files

TanStack Start Key Files

Step 4: Detect Routing Structure

Check for routing patterns based on architecture:

Vite SPA — React Router (check src/App.tsx):

• Look for <Routes>, <Route>, <BrowserRouter>
• Extract route paths and their components

TanStack Start — File-based routing (check app/routes/):

• Each .tsx file in app/routes/ is a route
• __root.tsx = root layout
• index.tsx = /
• about.tsx = /about
• $id.tsx = dynamic segment (e.g., /post/$id)
• Nested folders = nested routes

Step 5: Detect State Management

Check for state management patterns:

Step 6: Detect Data Flow

Build simplified data flow based on imports:

Pages → Components → Hooks → Services/Integrations → Supabase/API

Check for:

• Supabase client usage in hooks
• API service files
• Edge function invocations

---

Map Template

Generate this structure (~60 lines). Use the appropriate template based on detected architecture.

Template: Vite SPA (legacy)

## Project Structure Map

> Architecture: Vite SPA (CSR) — Quick navigation guide - run `/lovable:map --update` to refresh

### Directory Layout

src/ ├── components/ # [COMPONENT_PATTERN] UI components │ └── ui/ # shadcn/ui primitives (Button, Card, Dialog, etc.) ├── pages/ # Route pages ([PAGE_COUNT] pages) ├── hooks/ # Custom React hooks ([HOOK_COUNT] hooks) ├── lib/ # Utilities and helpers ├── integrations/ # External integrations │ └── supabase/ # Supabase client and generated types └── [OTHER_DIRS] # [PURPOSE]

supabase/ ├── functions/ # Supabase Edge Functions ([FUNCTION_COUNT] functions) — needs deploy └── migrations/ # Database migrations ([MIGRATION_COUNT] migrations)

### Key Files
| File | Purpose |
|------|---------|
| `src/App.tsx` | [DETECTED_PURPOSE] |
| `src/lib/utils.ts` | Shared utilities (cn, formatters) |
| `src/integrations/supabase/client.ts` | Supabase client configuration |
| [OTHER_KEY_FILES] | [PURPOSE] |

### Patterns
- **Components**: [COMPONENT_PATTERN_DESCRIPTION]
- **State**: [STATE_MANAGEMENT_PATTERN]
- **Data Flow**: Pages → Hooks → Supabase Client → Edge Functions

### Quick Lookup
| Looking for... | Check here |
|----------------|------------|
| UI components | `src/components/ui/` |
| Page routes | `src/pages/` or `src/App.tsx` |
| API calls | `src/hooks/` or `src/integrations/` |
| Types | `src/types/` or `src/integrations/supabase/types.ts` |
| Edge functions | `supabase/functions/[name]/index.ts` |

*Last updated: [TIMESTAMP]*

Template: TanStack Start (new)

## Project Structure Map

> Architecture: TanStack Start (SSR) — Quick navigation guide - run `/lovable:map --update` to refresh

### Directory Layout

app/ ├── routes/ # File-based routes ([ROUTE_COUNT] routes) │ ├── __root.tsx # Root layout │ └── *.tsx # Page routes (filename = URL path) ├── components/ # [COMPONENT_PATTERN] UI components │ └── ui/ # shadcn/ui primitives ├── lib/ # Utilities and helpers ├── integrations/ # External integrations │ └── supabase/ # Supabase client and generated types └── [OTHER_DIRS] # [PURPOSE]

supabase/ ├── functions/ # Supabase Edge Functions ([FUNCTION_COUNT] functions) — needs deploy └── migrations/ # Database migrations ([MIGRATION_COUNT] migrations)

### Key Files
| File | Purpose |
|------|---------|
| `app/routes/__root.tsx` | Root layout (wraps all pages) |
| `app/routes/index.tsx` | Home page (/) |
| `app/lib/utils.ts` | Shared utilities (cn, formatters) |
| `app/integrations/supabase/client.ts` | Supabase client configuration |
| `app.config.ts` | TanStack Start configuration |
| [OTHER_KEY_FILES] | [PURPOSE] |

### Patterns
- **Architecture**: SSR — pages render as HTML on the server before browser
- **Routing**: File-based (app/routes/*.tsx files = URL routes)
- **Server functions**: `*.server.ts` files auto-deploy via GitHub (no Lovable prompt needed)
- **Components**: [COMPONENT_PATTERN_DESCRIPTION]
- **State**: [STATE_MANAGEMENT_PATTERN]
- **Data Flow**: Routes (loaders) → Supabase Client → Edge Functions

### Quick Lookup
| Looking for... | Check here |
|----------------|------------|
| UI components | `app/components/ui/` |
| Page routes | `app/routes/` (file = route) |
| Root layout | `app/routes/__root.tsx` |
| Server functions | `app/**/*.server.ts` |
| API calls | `app/lib/` or `app/integrations/` |
| Types | `app/types/` or `app/integrations/supabase/types.ts` |
| Supabase Edge functions | `supabase/functions/[name]/index.ts` |

*Last updated: [TIMESTAMP]*

---

Edge Cases

Missing Directories

If a standard directory doesn't exist, omit it from the map. Don't show empty directories.

Non-Standard Structures

If structure doesn't match Lovable/React patterns: 1. List top-level directories with best-guess purposes 2. Identify entry point (package.json main/module field) 3. Note: "Non-standard structure - map may be incomplete"

Large Projects

If > 50 components or > 20 pages:

• Group by subdirectory instead of listing all
• Show counts: "components/ (45 components in 8 categories)"

Monorepo Detection

If packages/ or apps/ directory exists:

• Note monorepo structure
• Focus map on the primary app (usually apps/web/ or packages/app/)

---

Integration Points

With /lovable:init

Add Question 8.5:

Would you like me to generate a Project Structure Map?
This helps me navigate your codebase faster by documenting:
- Directory structure and purposes
- Key files and their roles
- Component organization patterns

Generate map? (yes/no)
Default: yes (recommended)

With /lovable:sync

Add --refresh-map flag:

• If map section exists in CLAUDE.md, optionally refresh it
• Detect if structure changed significantly since last generation
• Skip if no major changes to avoid unnecessary updates

With /lovable:map command

Standalone command options:

/lovable:map              # Generate and display map
/lovable:map --update     # Update CLAUDE.md with new map
/lovable:map --verbose    # Show detailed scanning output

---

Token Efficiency Guidelines

1. Use tree format - More compact than prose descriptions 2. Counts over lists - "12 components" not listing all 12 3. Tables for key info - Scannable, compact 4. Skip obvious files - Don't document package.json, .gitignore 5. Merge similar items - "hooks/" not "hooks/useAuth.ts, hooks/useData.ts..." 6. Purpose over description - "Auth handling" not "This file handles authentication..."

Target: Map should be quickly scannable in 10 seconds to find what you need.

Lovable Prompts Reference

Complete reference of Lovable prompts organized by category.

Edge Functions

Deployment

Creation

Debugging

Management

---

Database Tables

Creation

Modification

Relationships

Indexes

---

Migrations

---

RLS Policies

Enable RLS

Read Policies

Write Policies

Combined Policies

---

Storage

Buckets

Policies

---

Authentication

Providers

Triggers

Configuration

---

Database Functions (Postgres)

---

Database Triggers

---

Secrets (Manual)

Secrets cannot be set via prompts. Instructions:

1. Go to Cloud → Secrets 2. Click Add secret 3. Enter:

• Key: SECRET_NAME
• Value: Your secret value

4. Click Save 5. Run: "Redeploy edge functions to pick up new secrets"

Common secrets:

• OPENAI_API_KEY
• STRIPE_SECRET_KEY
• RESEND_API_KEY
• TWILIO_AUTH_TOKEN
• SENDGRID_API_KEY

Secret Detection Patterns and Algorithms

Reference guide for automatically detecting secrets required by a Lovable project during the init flow and deployment processes.

Overview

The secret detection system scans the codebase and infers secret requirements through multiple patterns: 1. Direct environment variable references in code 2. Configuration files (.env.example) 3. Context-based inference from imports and service usage

Detection Pattern 1: Edge Function Environment Variables

What to scan: All TypeScript files in Supabase Edge Functions

Files: supabase/functions/**/*.ts

Pattern: Deno.env.get("SECRET_NAME") or Deno.env.get('SECRET_NAME')

Regex:

Deno\.env\.get\(['"]([A-Z_]+)['"]\)

Extraction:

• Capture group 1 = SECRET_NAME
• Example: Deno.env.get("RESEND_API_KEY") → Extract RESEND_API_KEY

Edge Function Linking:

• Get function name from directory path: supabase/functions/FUNCTION_NAME/index.ts → FUNCTION_NAME
• Store: { name: "SECRET_NAME", usedIn: ["function_name"], source: "code" }

Example from codebase:

File: supabase/functions/send-email/index.ts

const apiKey = Deno.env.get("RESEND_API_KEY");
const webhookSecret = Deno.env.get("WEBHOOK_SECRET");

Detected secrets:

• RESEND_API_KEY (used in: send-email)
• WEBHOOK_SECRET (used in: send-email)

Detection Pattern 2: .env.example Files

What to scan: Environment variable example files

Files:

• .env.example
• .env.template
• .env.local.example
• env.example

Pattern: Lines starting with KEY=value (uppercase KEY before =)

Regex:

^([A-Z_]+)=

Extraction:

• Capture group 1 = KEY
• Example: OPENAI_API_KEY=sk-... → Extract OPENAI_API_KEY
• Ignore: Lines starting with # (comments)

Store: { name: "KEY", usedIn: [], source: "env_file", purpose: "inferred" }

Example .env.example:

# API Keys
OPENAI_API_KEY=sk-example
STRIPE_SECRET_KEY=sk_test_example
RESEND_API_KEY=re_example

# Database
SUPABASE_URL=https://xxxxx.supabase.co
SUPABASE_ANON_KEY=public_key

Detected secrets:

• OPENAI_API_KEY
• STRIPE_SECRET_KEY
• RESEND_API_KEY
• SUPABASE_URL
• SUPABASE_ANON_KEY

Detection Pattern 3: Context-Based Inference

What to scan: Import statements and code mentions of third-party services

Detection logic: Search for service names in code, then suggest their typical secret patterns

Service Patterns

OpenAI

• Search keywords: openai, gpt-, chatgpt, chat-completion, embedding
• Suggested secrets:
• OPENAI_API_KEY (always)
• OPENAI_ORG_ID (if organization usage detected)
• Purpose inference:
• If code mentions "embedding" → "OpenAI embeddings"
• If code mentions "chat" or "completion" → "OpenAI chat completions"
• Default → "OpenAI API access"

Stripe

• Search keywords: stripe, checkout, payment, subscription, invoice
• Suggested secrets:
• STRIPE_SECRET_KEY (always)
• STRIPE_WEBHOOK_SECRET (if webhook endpoint detected)
• STRIPE_PUBLISHABLE_KEY (if client-side code)
• Purpose inference:
• If "webhook" mentioned → "Stripe webhook verification"
• If "subscription" mentioned → "Stripe subscription management"
• Default → "Stripe payments"

Resend (Email)

• Search keywords: resend, send-email, email, transactional
• Suggested secrets:
• RESEND_API_KEY
• Purpose: "Email sending via Resend"

Twilio (SMS/Phone)

• Search keywords: twilio, sms, phone, voice, messaging
• Suggested secrets:
• TWILIO_ACCOUNT_SID
• TWILIO_AUTH_TOKEN
• TWILIO_PHONE_NUMBER (optional)
• Purpose inference:
• If "SMS" mentioned → "Twilio SMS service"
• If "voice" mentioned → "Twilio voice calls"
• Default → "Twilio SMS/Voice"

SendGrid (Email Alternative)

• Search keywords: sendgrid, sendgrid-api
• Suggested secrets:
• SENDGRID_API_KEY
• Purpose: "Email sending via SendGrid"

AWS Services

• Search keywords: aws, s3, lambda, dynamodb, sns, sqs
• Suggested secrets:
• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_REGION (optional)
• Purpose inference: Based on service (S3, Lambda, etc.)

PostgreSQL/Database

• Search keywords: postgresql, postgres, pg-, pool.query
• Suggested secrets:
• DATABASE_URL or DATABASE_PASSWORD
• DB_HOST, DB_PORT, DB_USER
• Purpose: "PostgreSQL database access"

Context-Based Detection Algorithm

function detectFromContext(codeContent: string): Secret[] {
  const detectedSecrets: Secret[] = [];
  const lowerContent = codeContent.toLowerCase();

  // OpenAI detection
  if (lowerContent.includes("openai") || lowerContent.includes("gpt")) {
    detectedSecrets.push({
      name: "OPENAI_API_KEY",
      source: "context",
      confidence: "high",
      purpose: inferOpenAIPurpose(codeContent)
    });
  }

  // Stripe detection
  if (lowerContent.includes("stripe")) {
    detectedSecrets.push({
      name: "STRIPE_SECRET_KEY",
      source: "context",
      confidence: "high",
      purpose: "Stripe payments"
    });

    if (lowerContent.includes("webhook")) {
      detectedSecrets.push({
        name: "STRIPE_WEBHOOK_SECRET",
        source: "context",
        confidence: "high",
        purpose: "Stripe webhook verification"
      });
    }
  }

  // ... more service checks

  return detectedSecrets;
}

function inferOpenAIPurpose(content: string): string {
  if (content.toLowerCase().includes("embedding")) {
    return "OpenAI embeddings";
  }
  if (content.toLowerCase().includes("completion") || content.toLowerCase().includes("chat")) {
    return "OpenAI chat completions";
  }
  return "OpenAI API access";
}

Detection Pattern 4: Supabase Secrets (Auto-Include)

Always include these secrets for Lovable Cloud projects:

• SUPABASE_URL - Supabase project URL
• SUPABASE_ANON_KEY - Supabase public API key
• SUPABASE_SERVICE_ROLE_KEY - Supabase admin access

Source: Read from src/integrations/supabase/client.ts if present

Example extraction:

File: src/integrations/supabase/client.ts

import { createClient } from '@supabase/supabase-js';

const supabaseUrl = "https://xyz.supabase.co";
const supabaseAnonKey = "eyJhbG...";

export const supabase = createClient(supabaseUrl, supabaseAnonKey);

Detected:

• SUPABASE_URL - Found in code
• SUPABASE_ANON_KEY - Found in code
• SUPABASE_SERVICE_ROLE_KEY - Auto-included for Lovable Cloud

Secret Grouping and Presentation

Group by Status

1. From Codebase (⚠️ Needs Setup)

• Detected via Patterns 1, 2, 3
• Not found in Lovable Cloud
• Requires user to add to Cloud → Secrets

2. From Lovable Cloud (✅ Already Configured)

• Extracted via browser automation
• Already present in Lovable's secrets manager
• Status shown as "In Lovable Cloud"

3. Suggested (💡 Optional)

• Context-based detection with lower confidence
• User should confirm if needed
• Can be added during init or skipped

Presentation Example

🔍 Secret Detection Results:

From codebase (needs setup):
- OPENAI_API_KEY (used in: chat-completion edge function)
  Purpose: OpenAI chat completions
- STRIPE_SECRET_KEY (used in: process-payment edge function)
  Purpose: Stripe payments

From Lovable Cloud (already configured):
✅ RESEND_API_KEY (already in: send-email, send-welcome)
✅ SUPABASE_SERVICE_ROLE_KEY (system)

Suggested (optional):
💡 STRIPE_WEBHOOK_SECRET (might be needed for: process-payment)
  Purpose: Stripe webhook verification

Any additional secrets to track?
(Enter comma-separated names, or press Enter to continue)

Merge and Deduplication

When combining results from multiple sources:

1. Primary source is code - If detected in codebase, use that 2. Merge usage info - If same secret found in multiple functions, list all 3. Track status - Mark if in Lovable Cloud or needs setup 4. Remove duplicates - Same secret from different patterns = single entry

Merge example:

Pattern 1 finds: RESEND_API_KEY (used in: send-email) Pattern 3 infers: RESEND_API_KEY (context: resend import) Lovable Cloud: RESEND_API_KEY (exists)

Result:

{
  "name": "RESEND_API_KEY",
  "purpose": "Email sending via Resend",
  "usedIn": ["send-email"],
  "status": "✅ In Lovable Cloud",
  "source": "merged"
}

Handling Edge Cases

Case 1: Secret in .env.example but not in Code

Example:

• .env.example contains ANALYTICS_KEY=...
• No code references it

Handling:

• Include in detected list
• Mark "usedIn" as empty or "(in env template)"
• Show with note: "Configured in .env.example but not used in current code"

Case 2: Secret Reference but No Value Pattern

Example:

const apiKey = Deno.env.get(someVariable);  // Can't extract secret name

Handling:

• Cannot detect automatically
• Skip this one
• Mention in summary: "Found dynamic env access - manual review recommended"

Case 3: Same Secret Used in Multiple Functions

Example:

• send-email/index.ts: Deno.env.get("RESEND_API_KEY")
• send-welcome/index.ts: Deno.env.get("RESEND_API_KEY")

Handling:

• Single entry for RESEND_API_KEY
• usedIn: ["send-email", "send-welcome"]
• Show as comma-separated in CLAUDE.md

Case 4: Secret Name Typos or Variations

Example:

Deno.env.get("OPENAI_API_KEY")
Deno.env.get("OPENAI_KEY")
Deno.env.get("OPENAI_API_SECRET")

Handling:

• Detect all variations
• Ask user to confirm/clarify: "Found 3 OpenAI-related secrets - are these all needed or typos?"
• Store user's clarification in CLAUDE.md

Integration Points

During Init Flow

• After Q4 (Backend selection): Scan codebase
• During Q6 (Secret Detection Method):
• If auto-detect: Run all 4 patterns
• If browser automation available: Get from Lovable Cloud
• Merge and present results
• After Q6: Ask for additional secrets

During deploy-edge Command

• Scan function being deployed for new secrets
• Compare against CLAUDE.md secrets table
• Warn if new secret detected that's not in CLAUDE.md or not configured

During Secret Dependency Analysis

Link secrets to functions:

• When user changes Edge Function, check if new secrets needed
• Suggest adding to CLAUDE.md Secrets table
• Warn if required secret not in Lovable Cloud

Performance Considerations

Timeouts:

• Codebase scanning: 5 seconds max
• .env file parsing: < 100ms
• Context scanning: < 2 seconds
• Browser automation: 30 seconds max

Caching:

• Cache scan results during single init session
• Don't re-scan if user navigates back
• Clear cache between separate init runs

Testing the Detection Logic

Test Case 1: Mixed Project

Setup:

• 3 Edge Functions: send-email, process-payment, chat-completion
• .env.example with 5 keys
• Code uses some keys, env file has others

Expected:

• Detect all keys from code
• Detect all keys from .env
• Merge with no duplicates
• Show ~5-7 total secrets depending on overlap

Test Case 2: Service Context Detection

Setup:

• Project imports openai and stripe packages
• Code references chatCompletion and payment processing
• No direct env.get() for some typical secrets

Expected:

• Detect direct references from code
• Infer STRIPE_WEBHOOK_SECRET from webhook context
• Infer OPENAI_API_KEY from import presence
• Present with confidence levels

Test Case 3: Browser Automation Merging

Setup:

• 3 secrets in code: OPENAI_API_KEY, STRIPE_SECRET_KEY, NEW_SECRET
• 2 secrets in Lovable Cloud: RESEND_API_KEY, STRIPE_SECRET_KEY
• Browser automation succeeds

Expected:

• Show OPENAI_API_KEY (⚠️ not in Cloud)
• Show STRIPE_SECRET_KEY (✅ in Cloud)
• Show RESEND_API_KEY (✅ in Cloud)
• Show NEW_SECRET (⚠️ not in Cloud)
• Total: 4 unique secrets

---

This reference enables the init command to provide intelligent, automated secret detection while maintaining a fallback for manual entry.