@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

npm install @base44/vite-plugin

Usage

// 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):

base44 — Core configuration: path aliases (@/ → /src/), environment variables, dependency optimization, and legacy SDK import resolution.
iframe-hmr — Sets CORS and frame-ancestors headers to allow iframe embedding.
error-overlay — Replaces Vite's default error overlay with a custom one that reports errors to the parent window.
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:

Generate local HTTPS certificates:
```
mkcert localhost
```

Start the dev server (with optional watch mode):

npm run dev       # serve dist/statics/ on https://localhost:3201
npm run dev -- -w # same, with auto-rebuild on changes

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

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

License

MIT

3.9 KiB Raw Blame History