npm package: @lovable.dev/lovite
Description: Vite config wrapper for Lovable sandbox environments
Author: Emil Fagerholm
Latest version: 0.0.1

# lovite

Vite config wrapper for Lovable sandbox environments.

## Installation

```bash
npm install lovite
```

or

```bash
pnpm add lovite
```

or

```bash
yarn add lovite
```

## Usage

Simply replace Vite's `defineConfig` with lovite's:

```typescript
// Before
import { defineConfig } from 'vite';

// After
import { defineConfig } from 'lovite';
import react from '@vitejs/plugin-react-swc';
import path from 'path';

export default defineConfig({
  server: {
    host: '::',
    port: 8080,
  },
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
});
```

## How It Works

lovite provides three layers of automatic configuration:

### 1. Base Configuration (Always Applied)

- **Path Alias**: Automatically configures `@` to resolve to `./src` for cleaner imports

### 2. Development Mode Enhancements (All Environments)

In development mode, lovite automatically configures settings to improve the developer experience:

- **Component Tagging**: Automatically injects the `lovable-tagger` plugin for component identification
- **Source Maps**: Enables source maps (`build.sourcemap: true`) for better debugging

These enhancements apply in **all** environments (local and sandbox) when running in development mode.

### 3. Sandbox Configuration Enforcement

lovite automatically detects when your code is running in a Lovable sandbox environment (via the `LOVABLE_SANDBOX` environment variable) and enforces specific configurations required for proper operation:

#### Enforced Settings (Sandbox Only)

When running in a Lovable sandbox, the following settings are automatically enforced:

- **Port**: `8080` (required for Lovable's proxy routing)
- **Host**: `::` (IPv6 support for network binding)
- **StrictPort**: `true` (fail fast if port is unavailable)
- **Headers**: All custom headers are removed (Lovable's proxy manages headers)
- **CORS**: Uses Vite's default CORS settings (Lovable's proxy handles actual CORS)
- **Proxy**: All proxy configurations are removed (Lovable's proxy handles routing)

## Automatic Features

### Path Aliases

lovite automatically configures the `@` path alias to resolve to your `src` directory:

```typescript
// No configuration needed - this just works
import { Button } from "@/components/ui/button";
import { useAuth } from "@/hooks/use-auth";
```

You don't need to manually configure `resolve.alias` in your vite.config - lovite handles this for you.

### Local Development

When running locally (outside a Lovable sandbox), lovite only applies development mode enhancements (component tagger and sourcemaps in dev mode). Your server configuration is used exactly as written.

In sandbox mode, server settings are enforced for compatibility with Lovable's infrastructure.

```typescript
// Local: uses port 3000, dev enhancements applied
// Sandbox: port overridden to 8080, dev enhancements applied
export default defineConfig({
  server: {
    port: 3000,  // Used locally, overridden to 8080 in sandbox
  },
});
```

## Validation & Warnings

lovite validates your configuration and warns about potential issues:

### Server Headers

All server headers are removed in sandbox mode to prevent conflicts with Lovable's proxy infrastructure. If you configure any headers, lovite will warn you and they will be removed.

```typescript
// This will warn in sandbox mode - headers are removed
export default defineConfig({
  server: {
    headers: {
      'X-Custom-Header': 'value', // Will be removed in sandbox
      'Cache-Control': 'no-cache', // Will be removed in sandbox
    },
  },
});
```

### Proxy Configuration

All proxy configurations are removed in sandbox mode. lovite validates and warns about potential issues before removal:
- External proxy targets (could bypass security)
- WebSocket proxies (could interfere with HMR)
- Origin-changing proxies (could break CORS)

```typescript
// These will warn and be removed in sandbox mode
export default defineConfig({
  server: {
    proxy: {
      '/api': 'https://external-api.com', // External URL - will warn
      '/ws': { target: 'ws://localhost:3001', ws: true }, // WebSocket - will warn
      '/local': 'http://localhost:4000', // Even localhost proxies are removed
    },
  },
});
```

**Note**: In local development (outside sandbox), proxy configurations work normally. They are only removed when running in a Lovable sandbox environment.

### CORS Configuration

Custom CORS configurations will be overridden in sandbox mode to ensure compatibility with Lovable's proxy. lovite will warn you if it detects custom CORS settings.

```typescript
// This will warn in sandbox mode
export default defineConfig({
  server: {
    cors: { origin: 'https://example.com' }, // Will be overridden
  },
});
```

## API

### `defineConfig(config)`

Wraps Vite's `defineConfig` function. Accepts the same arguments and returns the same types:

- `defineConfig(config: UserConfig): UserConfig`
- `defineConfig(config: Promise<UserConfig>): Promise<UserConfig>`
- `defineConfig(config: (env: ConfigEnv) => UserConfig): (env: ConfigEnv) => UserConfig`
- `defineConfig(config: (env: ConfigEnv) => Promise<UserConfig>): (env: ConfigEnv) => Promise<UserConfig>`

### Function-based Config

lovite fully supports function-based configs:

```typescript
export default defineConfig(({ mode }) => ({
  plugins: [react()], // lovite automatically adds componentTagger() and configures sourcemaps in dev mode
}));
```

### Async Config

Async configurations are also supported:

```typescript
export default defineConfig(async ({ mode }) => {
  const data = await fetchSomeConfig();
  return {
    plugins: [react()],
    define: data,
  };
});
```

## TypeScript

lovite is written in TypeScript and provides full type definitions. All Vite types are preserved, so you get the same IntelliSense and type checking as with Vite's native `defineConfig`.

```typescript
import { defineConfig } from 'lovite';
import type { UserConfig } from 'vite';

// Full type inference and autocomplete
export default defineConfig({
  server: {
    port: 8080, // Autocomplete works
  },
});
```

## Why lovite?

Lovable's sandbox environment runs your Vite dev server behind a proxy that:
- Routes requests based on subdomain
- Adds sandbox identification headers
- Manages CORS and security
- Handles WebSocket connections for HMR

lovite ensures your Vite config is compatible with this infrastructure without requiring manual configuration changes.

## License

MIT