97 lines
3.9 KiB
Markdown
97 lines
3.9 KiB
Markdown
# @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
|