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

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:

   mkcert localhost

2. 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

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

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

License

MIT