# @base44/vite-plugin

Vite plugin for Base44 applications running in sandboxed iframes. Provides error tracking, HMR notifications, visual editing, navigation tracking, and legacy SDK compatibility.

## Installation

```bash
npm install @base44/vite-plugin
```

## Usage

```ts
// vite.config.ts
import base44 from "@base44/vite-plugin";

export default {
  plugins: [
    base44({
      legacySDKImports: false,
      hmrNotifier: true,
      navigationNotifier: true,
      visualEditAgent: true,
    }),
  ],
};
```

### Options

| Option               | Type      | Default | Description                                         |
| -------------------- | --------- | ------- | --------------------------------------------------- |
| `legacySDKImports`   | `boolean` | `false` | Enable legacy SDK import resolution via compat layer |
| `hmrNotifier`        | `boolean` | `false` | Notify parent window of HMR update lifecycle         |
| `navigationNotifier` | `boolean` | `false` | Track URL changes and notify parent window           |
| `visualEditAgent`    | `boolean` | `false` | Enable interactive visual element editing            |

## Architecture

### Plugin Composition

The plugin registers four sub-plugins when running in a sandbox (`MODAL_SANDBOX_ID` is set):

1. **base44** — Core configuration: path aliases (`@/` → `/src/`), environment variables, dependency optimization, and legacy SDK import resolution.
2. **iframe-hmr** — Sets CORS and `frame-ancestors` headers to allow iframe embedding.
3. **error-overlay** — Replaces Vite's default error overlay with a custom one that reports errors to the parent window.
4. **html-injections** — Injects sandbox-side scripts into the HTML.

Outside a sandbox, only the core plugin runs (with optional API proxy support via `VITE_BASE44_APP_BASE_URL`).

### Sandbox Injections

In **dev mode**, individual `<script type="module" src="...">` tags are injected for each feature, loaded directly from `node_modules`:

- **Error handlers** (`unhandled-errors-handlers.js`) — Global `error` and `unhandledrejection` listeners that report to the parent via `postMessage`.
- **Mount observer** (`sandbox-mount-observer.js`) — `MutationObserver` that detects when instrumented elements (`data-source-location`) are rendered.
- **HMR notifier** (`sandbox-hmr-notifier.js`) — Forwards Vite's `beforeUpdate`/`afterUpdate` events to the parent.
- **Navigation notifier** (`navigation-notifier.js`) — Intercepts `pushState`, `replaceState`, and `popstate` to track URL changes.

These are self-executing scripts — they run as soon as the browser loads them, with no setup call required.

The **visual edit agent** is the exception. It's a larger module (~560 lines) that is bundled separately via `tsup` into `dist/statics/index.mjs` and loaded via a dynamic `import()`. This allows local dev iteration: add `?sandbox-bridge=local` to load it from a local HTTPS dev server instead of `node_modules`.

In **production**, an inline analytics tracker script is injected instead.

### Local Development (Visual Edit Agent)

To iterate on the visual edit agent locally without publishing:

1. Generate local HTTPS certificates:
   ```bash
   mkcert localhost
   ```

2. Start the dev server (with optional watch mode):
   ```bash
   npm run dev       # serve dist/statics/ on https://localhost:3201
   npm run dev -- -w # same, with auto-rebuild on changes
   ```

3. Add `?sandbox-bridge=local` to your app's URL to load the agent from `localhost:3201` instead of `node_modules`.

### Legacy SDK Compatibility

When `legacySDKImports` is enabled, imports of `/entities`, `/functions`, `/integrations`, and `/agents` are resolved to compatibility modules in `compat/`. These use `Proxy` objects to route calls to the Base44 SDK client.

## Building

```bash
npm run build          # TypeScript compilation (plugin)
npm run build:bridge   # tsup bundle (bridge ES module for browsers)
```

## License

MIT