Lovable Setup Expert

Expert assistant for configuring projects to work with Lovable's build and preview environment, especially in monorepo setups.

When to Use This Skill

Use this skill when:

• Setting up a new project for Lovable deployment
• Fixing Lovable build or preview errors
• Migrating a project to monorepo structure with Lovable
• Troubleshooting "Missing script", PostCSS, or module resolution errors in Lovable
• Configuring Vite/Webpack for Lovable's build environment

Common Lovable Issues and Solutions

1. Missing Script Errors

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

Cause: Lovable runs commands from the monorepo root, but scripts are defined in workspace packages.

Solution: 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]",
    "preview": "npm run preview --workspace=apps/[app-name]",
    "test": "npm run test --workspace=apps/[app-name]"
  }
}

Files to Check:

• Root package.json - Must have delegation scripts
• App package.json - Must have actual implementation scripts

2. PostCSS/Tailwind Module Resolution

Error: Cannot find module 'tailwindcss' or Cannot find module 'autoprefixer'

Cause: postcss.config.js at root can't resolve plugins when Vite runs in workspace context.

Solution: Move postcss.config.js to the app directory:

mv postcss.config.js apps/[app-name]/postcss.config.js

Files to Check:

• apps/[app-name]/postcss.config.js - Should exist
• postcss.config.js (root) - Should NOT exist
• apps/[app-name]/tailwind.config.ts - Should exist in app directory

PostCSS Config Example:

export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

3. Vite Workspace Package Resolution

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

Cause: Vite doesn't know how to handle React imports from workspace packages during build.

Solution: Update vite.config.ts with workspace package configuration:

export default defineConfig({
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
      "@shared-auth": path.resolve(__dirname, "../../packages/shared-auth/src"),
      // ... other workspace packages
    },
  },
  optimizeDeps: {
    include: [
      "react",
      "react-dom",
      "react/jsx-runtime",
    ],
  },
  build: {
    commonjsOptions: {
      include: [/packages\/.*/, /node_modules/],
    },
  },
});

Files to Check:

• apps/[app-name]/vite.config.ts - Must have optimizeDeps and build.commonjsOptions
• Workspace package paths in aliases should use ../../packages/[name]/src

4. Workspace Dependencies Not Declared

Error: Missing from lock file: @your-org/package-name

Cause: Workspace packages referenced via path aliases but not declared as dependencies.

Solution: Add workspace packages to app's package.json dependencies:

{
  "dependencies": {
    "@your-org/shared-auth": "*",
    "@your-org/shared-utils": "*",
    "@your-org/ui": "*",
    // ... other workspace packages
  }
}

Then regenerate lock file:

npm install

Files to Check:

• apps/[app-name]/package.json - All workspace packages should be in dependencies
• package-lock.json - Workspace packages should NOT be marked as "extraneous"
• Run npm ls to verify no extraneous packages

5. Host and Port Configuration

Error: Preview server not accessible or wrong port

Cause: Lovable expects specific host and port configuration.

Solution: Update app package.json scripts:

{
  "scripts": {
    "dev": "vite --host 0.0.0.0 --port 5173",
    "preview": "vite preview --host 0.0.0.0 --port 4173"
  }
}

Configuration:

• Dev server: 0.0.0.0:5173
• Preview server: 0.0.0.0:4173
• Use 0.0.0.0 instead of localhost for container access

Diagnostic Checklist

When encountering Lovable build issues, check in order:

1. Package Structure

# Root should have delegation scripts
cat package.json | grep -A 5 '"scripts"'

# App should have implementation scripts
cat apps/[app-name]/package.json | grep -A 10 '"scripts"'

# Workspace packages should be declared
cat apps/[app-name]/package.json | grep '@your-org'

2. Configuration Files

# PostCSS config should be in app directory
ls -la apps/[app-name]/postcss.config.js

# Tailwind config should be in app directory
ls -la apps/[app-name]/tailwind.config.ts

# Vite config should have workspace support
cat apps/[app-name]/vite.config.ts | grep -A 5 'optimizeDeps'

3. Dependencies

# Regenerate lock file
npm install

# Check for extraneous packages
npm ls 2>&1 | grep extraneous

# Verify workspace linking
npm ls @your-org/* 2>&1 | head -20

4. Build Test

# Test dev build
npm run build:dev

# Test preview
npm run preview

# Check output
ls -la apps/[app-name]/dist/

Step-by-Step Setup Guide

Initial Monorepo Setup for Lovable

1. Create root package.json with workspaces:

{
  "name": "your-monorepo",
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "scripts": {
    "dev": "npm run dev --workspace=apps/your-app",
    "build": "npm run build --workspace=apps/your-app",
    "build:dev": "npm run build:dev --workspace=apps/your-app",
    "preview": "npm run preview --workspace=apps/your-app"
  }
}

2. Move config files to app directory:

mv postcss.config.js apps/your-app/
mv tailwind.config.ts apps/your-app/  # if at root

3. Update Vite config with workspace support (see section 3 above)

4. Declare workspace dependencies in app package.json (see section 4 above)

5. Regenerate dependencies:

rm -rf node_modules package-lock.json
npm install

6. Test locally:

npm run build:dev
npm run preview

7. Commit all changes:

git add .
git commit -m "Configure for Lovable deployment"
git push

Common Patterns

Multi-App Monorepo

// Root package.json
{
  "scripts": {
    "dev:app1": "npm run dev --workspace=apps/app1",
    "dev:app2": "npm run dev --workspace=apps/app2",
    "build:app1": "npm run build --workspace=apps/app1",
    "build:app2": "npm run build --workspace=apps/app2"
  }
}

Environment-Specific Builds

// App package.json
{
  "scripts": {
    "dev": "vite --mode development --host 0.0.0.0",
    "build": "vite build --mode production",
    "build:dev": "vite build --mode development",
    "build:staging": "vite build --mode staging"
  }
}

TypeScript Paths

// vite.config.ts
resolve: {
  alias: {
    "@": path.resolve(__dirname, "./src"),
    "@ui": path.resolve(__dirname, "../../packages/ui/src"),
    "@shared/*": path.resolve(__dirname, "../../packages/*/src"),
  },
}

// tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"],
      "@ui/*": ["../../packages/ui/src/*"],
      "@shared/*": ["../../packages/*/src/*"]
    }
  }
}

Troubleshooting Commands

# Check if scripts exist
npm run build:dev --dry-run

# View workspace structure
npm ls --depth=0

# Check for missing dependencies
npm ci --dry-run

# Verify Vite can find configs
npx vite --help

# Test PostCSS
npx postcss --help

# Check node_modules resolution
node -p "require.resolve('tailwindcss')"

Files This Skill May Modify

• package.json (root) - Add delegation scripts
• apps/[app-name]/package.json - Add workspace dependencies, update scripts
• apps/[app-name]/vite.config.ts - Add workspace package support
• postcss.config.js - Move to app directory
• package-lock.json - Regenerate with workspace dependencies

Best Practices

1. Always test locally before pushing to Lovable
2. Use consistent naming for workspace packages (@org/name)
3. Document build modes in README (dev, staging, production)
4. Keep configs in app directory when possible (postcss, tailwind)
5. Use path aliases instead of relative imports
6. Declare all workspace dependencies explicitly
7. Regenerate lock file after changing dependencies
8. Test both dev and preview modes locally

Example: Complete Lovable Setup

See the committed changes in this repository for a complete working example:

• Commit 95d2adb: Added build:dev scripts
• Commit a568eaa: Moved PostCSS config
• Commit 8c59755: Fixed Vite workspace resolution
• Commit b808ac8: Added workspace dependencies

Related Documentation

• Lovable Docs: https://docs.lovable.dev
• Vite Configuration: https://vitejs.dev/config/
• npm Workspaces: https://docs.npmjs.com/cli/v8/using-npm/workspaces
• PostCSS: https://postcss.org/