Vite Plugin Reference

The @entrinsik/vite-plugin-informer package provides everything you need for local Magic App development and deployment. It includes a Vite plugin, CLI commands, and workspace management tools.

Installation

npm install --save-dev @entrinsik/vite-plugin-informer

Plugin Setup

Add the plugin to your vite.config.js:

import { defineConfig } from 'vite';
import informer from '@entrinsik/vite-plugin-informer';

export default defineConfig({
    plugins: [informer()]
});

Plugin Options

The plugin accepts an optional configuration object:

informer({
    mock: {
        theme: 'dark',                    // 'light' (default) or 'dark'
        roles: ['approver', 'manager'],   // Mock role IDs for testing
        report: {                         // Override app context
            id: 'custom-id',
            name: 'My Test App'
        },
        user: {                           // Mock user identity
            username: 'test-user',
            displayName: 'Test User'
        }
    },
    proxy: {                              // http-proxy options for /api proxy
        secure: false                     // Disable SSL cert validation
    }
})

Option	Type	Default	Description
mock	object	{}	Overrides for the window.__INFORMER__ context object
mock.theme	string	'light'	Theme mode injected into the app
mock.roles	string[]	[]	Role IDs for testing role-based features
mock.report	object	{ id: 'dev-local', name: 'Local Development' }	App identity context
mock.user	object	—	Mock user identity for testing user-specific features
proxy	object	{}	Extra http-proxy options merged into the /api proxy config

Any properties in mock are spread into the default window.__INFORMER__ object, so you can override individual fields without replacing the whole thing.

Proxy Options

The proxy option passes through to Vite's underlying http-proxy instance. Common uses:

// Disable SSL certificate validation (self-signed certs, corporate proxies)
informer({ proxy: { secure: false } })

What the Plugin Does

In Dev Mode (npm run dev)

1. API Proxy — Proxies all /api/* requests to your Informer server with automatic authentication (from .env). Your app code makes fetch('/api/...') calls without worrying about auth headers or CORS.

2. Context Injection — Injects a window.__INFORMER__ object into your HTML so your app can read its context (theme, roles, app ID) the same way it does in production.

3. Server Route Middleware — If a server/ directory exists, mounts Connect middleware at /api/_server that loads and executes your handler files locally via Vite's ssrLoadModule. Handlers get hot-reloaded on save.

4. Workspace Auto-Provisioning — If a migrations/ directory exists, automatically creates a dev workspace datasource on the Informer server and runs pending migrations. The workspace ID is saved to .env as INFORMER_DEV_WORKSPACE.

5. Relative Base Path — Sets Vite's base to './' so built assets use relative paths (required for Informer's serving model).

In Build Mode (npm run build)

The plugin only sets the relative base path. All other features are dev-only.

Environment Variables

Configure connection settings in .env:

# Required: Informer server URL
INFORMER_URL=http://localhost:3000

# Auth option 1: API Key (recommended)
INFORMER_API_KEY=your-api-key

# Auth option 2: Basic auth
INFORMER_USER=admin
INFORMER_PASS=yourpassword

# Auto-set by workspace:init (do not edit manually)
INFORMER_DEV_WORKSPACE=admin:my-app-dev

Multi-Environment Support

Use Vite's --mode flag to target different Informer servers (e.g., test, production):

# Dev against local (default — uses .env)
npm run dev

# Dev against test server (uses .env.test)
npm run dev -- --mode test

# Deploy to production (uses .env.production)
npm run deploy -- --mode production

Create mode-specific env files alongside your default .env:

# .env — local development (default)
INFORMER_URL=http://localhost:3000
INFORMER_API_KEY=dev-key-123

# .env.test — test server
INFORMER_URL=https://test.example.com
INFORMER_API_KEY=test-key-456

# .env.production — production server
INFORMER_URL=https://app.example.com
INFORMER_API_KEY=prod-key-789

When a mode is active, workspace:init writes INFORMER_DEV_WORKSPACE to the mode-specific file (e.g., .env.test), keeping workspace IDs separate per environment.

Monorepo / Parent Directory Support

The plugin walks up the directory tree looking for .env files, so you can share credentials across apps in a monorepo:

my-apps/
├── .env                    # shared: INFORMER_URL, INFORMER_API_KEY
├── .env.test               # shared test credentials
├── apps/
│   ├── sales-dashboard/
│   │   ├── .env            # app-specific: INFORMER_DEV_WORKSPACE
│   │   └── ...
│   └── hr-portal/
│       ├── .env
│       └── ...

Resolution order (first value wins):

1. <project>/.env.<mode> — mode-specific local overrides
2. <project>/.env — local defaults
3. <parent>/.env.<mode> — shared mode-specific (walks up to first parent with a .env)
4. <parent>/.env — shared defaults

The --mode development (Vite's default when running vite dev) skips mode-specific files since .env already serves that purpose.

CLI Commands

The package provides three CLI commands, available as npx commands or via package.json scripts:

Command	Script	Description
informer-init	—	Scaffold a new project (interactive)
informer-deploy	npm run deploy	Build and deploy to Informer
informer-workspace	npm run workspace:*	Manage dev workspace

informer-init

Initializes an existing Vite project for Magic App development:

npx informer-init

This command:

1. Prompts for an app name
2. Generates a stable UUID for the app
3. Adds the plugin to devDependencies
4. Adds deploy and workspace:* scripts to package.json
5. Updates vite.config.js to include the plugin
6. Creates .env and .env.example with connection templates
7. Creates informer.yaml with commented examples
8. Updates .gitignore to exclude .env

informer-deploy

See Deployment for full documentation. Supports --mode <name>.

informer-workspace

See Workspace CLI for full documentation. Supports --mode <name>.

How the API Proxy Works

When your app makes a request like fetch('/api/datasets/admin:sales/_search'), the plugin:

1. Intercepts the request via Vite's built-in proxy
2. Forwards it to ${INFORMER_URL}/api/datasets/admin:sales/_search
3. Adds an Authorization header (Bearer token or Basic auth from .env)
4. Returns the response to your app

This means your app code is identical in dev and production — no environment-specific URL handling needed.

Server Route Proxy

Requests to /api/_server/* are handled differently — they're not proxied to the Informer server. Instead, the plugin loads your server/*.js handler files locally using Vite's ssrLoadModule and executes them in-process. This gives you:

• Hot reload — Edit a server handler and it takes effect immediately
• Source maps — Stack traces point to your original source
• ESM support — Use import/export syntax in handlers

The query() callback in server handlers proxies SQL to the dev workspace via the Informer server's _sql endpoint. The fetch() callback proxies API calls through the Informer server with your credentials.

Binary Responses from Server Routes

Server route handlers can return raw bytes (images, PDFs, file downloads) by setting encoding: 'base64' on the response object. Set headers['content-type'] to control how the browser interprets the response — it's forwarded verbatim instead of being defaulted to application/json.

// server/attachments/[id].js — serve a file attachment from a bytea column
export async function GET({ query, request }) {
    const [row] = await query(
        `SELECT encode(data, 'base64') AS data, mime_type, name
         FROM attachments WHERE id = $1`,
        [request.params.id]
    );
    if (!row) return { status: 404, body: { error: 'Not found' } };
    return {
        status: 200,
        headers: {
            'content-type': row.mime_type,
            'content-disposition': `inline; filename="${row.name}"`
        },
        body: row.data,
        encoding: 'base64'
    };
}

This is the recommended pattern for serving attachments stored as bytea — Postgres' encode(col, 'base64') does the encoding in SQL so the handler just passes the string through. See the magic-apps skill reference for the full handler API.