Configuration

MikroCanvas is local-first by default. It can run as a static app with IndexedDB storage, or with the optional MikroCanvas API for publishing board snapshots that open when you have the board ID.

Browser Runtime

Boards are stored in IndexedDB for the current browser profile and origin. Moving the app to another origin creates a separate browser storage area.

The static app reads config.json at startup:

{
  "mode": "local",
  "apiBaseUrl": ".",
  "boardSnapshots": {
    "enabled": false
  }
}

When the API server hosts the app it serves a runtime config with mode: "api", boardSnapshots.enabled: true, and apiBaseUrl pointing to the server.

When Cloudflare Pages builds the static app, the build writes an API-mode dist/config.json automatically. By default it points at https://canvas-api.mikrosuite.com; set MIKROCANVAS_PUBLIC_API_BASE_URL in the Pages build environment to use another API origin.

In API mode, board edits still save locally in IndexedDB. The top bar shows local save status, and a failed local save raises a toast so the user knows to retry or export JSON before leaving.

Published Snapshots

API-backed snapshots are open if you have the board ID. A URL containing ?board=<id> loads that published snapshot from the API and stores it locally in the browser.

Use the link button in the top bar, or Cmd/Ctrl+K and “Publish snapshot link”, to upload the current local board snapshot and copy its URL. Later edits remain local until the user publishes again.

Operators can configure an optional admin token for recovery deletes of remote snapshots.

There is no MikroAuth requirement for this mode. Treat board IDs and copied links as bearer links to the published snapshot.

Deployment Settings

Any static host that serves HTML, CSS, JavaScript, SVG, PNG, ICO, and web manifest files is enough. Configure caching so index.html, config.json, and unversioned app assets can update quickly.

The API server can be configured with mikrocanvas.config.json, environment variables, or CLI flags:

{
  "adminToken": "",
  "appUrl": "http://127.0.0.1:3000",
  "databasePath": "data/mikrocanvas.sqlite",
  "host": "127.0.0.1",
  "port": 3000
}

Equivalent environment variables include MIKROCANVAS_APP_URL, MIKROCANVAS_DB_PATH, MIKROCANVAS_HOST, MIKROCANVAS_PORT, and MIKROCANVAS_ADMIN_TOKEN. The matching CLI flags are --app-url, --database-path, --host, --port, and --admin-token.