Developing Standalone

Developing the standalone (in-browser) build

apps/standalone runs the entire Trilium stack in the browser with no server: the ordinary apps/client UI on the page, and @triliumnext/core — plain JS, the same code the server runs — inside a dedicated Web Worker on top of SQLite compiled to WASM (@sqlite.org/sqlite-wasm, not sql.js) persisted in the origin's OPFS through the SAHPool VFS. It ships as a PWA to app.triliumnotes.org (Cloudflare Pages, deploy-app.yml, PR previews included) and is the webDir of the Capacitor mobile app (developing-capacitor-mobile skill). There is no apps/standalone-desktop.

Layout

apps/standalone/
  src/index.html, main.ts         # page bootstrap: SW registration, leadership claim, worker start, standaloneApi
  src/desktop.ts                  # re-exports apps/client/src/desktop — the client entry
  src/sw.ts                       # service worker: caches assets, forwards follower tabs' API requests to the leader
  src/leader_election.ts          # Web Lock decides which tab owns the database worker
  src/local-bridge.ts             # page ⇄ worker protocol (LOCAL_REQUEST/RESPONSE, WS_MESSAGE, HTTP_REQUEST, backup/restore)
  src/local-server-worker.ts      # the worker: opens SQLite, initializeCore(), routes requests
  src/ios-interceptors.ts         # iOS Capacitor only (see mobile skill)
  src/error-overlay.ts            # full-screen surface for fatal startup failures
  src/lightweight/                # browser implementations of every core provider + standalone-only routes
  src/services/                   # image provider, Capacitor HTTP handler
  src/stubs/                      # officeparser entry + Buffer polyfill, empty stubs for pdfjs/tesseract/puppeteer
  src/test_setup.ts               # boots core with the real lightweight providers under vitest/happy-dom
  public/_headers, manifest.webmanifest, favicon.ico
  e2e/multi_tab.spec.ts, extra_window.spec.ts
  vite.config.mts                 # root is src/; aliases, stubs, asset copies, worker + SW build, vitest config

Request flow

1. main.ts requires a service worker (secure context: HTTPS or localhost — otherwise it throws a message explaining that), registers ./sw.js with scope /, reloads once if the SW installed but doesn't control the page yet, and exposes window.standaloneApi (restore.importBackup, backup.downloadDatabase) — the client's escape hatch for things carrying a whole file, the twin of desktop's window.electronApi. The leader also publishes localFetch there (step 3).
2. Leader election (leader_election.ts): the OPFS SAHPool VFS takes exclusive sync-access handles, and createSyncAccessHandle exists only in a dedicated worker, so exactly one tab per origin can own the database. A Web Lock (trilium-standalone-db, held for the tab's lifetime) picks it; only the winner calls startLocalServerWorker(); when it closes the browser releases the lock and a waiting tab is promoted. Where Web Locks are missing (some WebViews) the tab assumes it is alone.
3. The leader answers its own API calls. Winning the lock also publishes localFetch (local-bridge.ts) on window.standaloneApi, and the client prefers it over its XHR transport — in ajax() (apps/client/src/services/server.ts) and in setupGlob()'s /bootstrap (apps/client/src/index.ts). Without it the leader's own request leaves as an XHR, is intercepted by the service worker, and is posted back into the page it started in, to reach a worker that page owns. localAjax() matches the XHR path's contract — headers, JSON body, CSRF refresh-and-retry-once, the silent* suppressions, raw, and a timeout of opts.timeoutMs ?? DEFAULT_TIMEOUT. Build with VITE_DISABLE_LOCAL_FETCH=true to take the service worker's route instead, which is what compares the two transports. Follower tabs leave localFetch unset; so do upload(), chunked_upload.ts and the LLM stream, which carry FormData or want the body as it arrives.
4. Service worker (sw.ts): cache-first for hashed assets, network-first otherwise; requests under LOCAL_API_PREFIXES (/bootstrap, /api/, /sync/, /search/, from local-bridge.ts) are forwarded with LOCAL_FETCH to the leader client, found via a cached id, WHO_IS_LEADER / LEADER_REPLY probing, and one retry on NOT_LEADER (leadership can flip while a request is in flight). Since step 3 this carries follower tabs, engine-initiated loads (<img src="api/images/…">, fonts, themes) and the call sites that reach past server.ts, rather than the whole API surface. Backup downloads stream over a MessageChannel from the leader. It must let /_trilium_native_http/ fall through (Android native proxy) and has a defensive guard for capacitor://.
5. The worker (local-server-worker.ts): waits for the previous worker's OPFS access handles to be released (waitForSahPoolRelease — a reload races the browser's asynchronous release, and installOpfsSAHPoolVfs() reacts to an acquisition failure by deleting the pool directory, so the pool must be acquirable before it runs — a wait that reaches its deadline ends the boot instead of installing anyway), then installs the SAHPool VFS once — failure is a fatal startup error painted by error-overlay.ts, never an in-memory fallback (TRILIUM_INTEGRATION_TEST=memory builds seed a fixture into the pool, so writes survive reloads within a test). It then calls initializeCore({...}) with the lightweight/* providers, registers createConfiguredRouter() (BrowserRouter mimicking Express, path params + query strings), then answers LOCAL_REQUEST messages. DbLock (lightweight/db_lock.ts) serialises createAsyncRoute handlers (imports) that hold a transaction across awaits against the single connection — synchronous routes keep a zero-overhead path. WS_MESSAGE replaces the WebSocket in both directions. Anything that escapes after startup is reported as WORKER_ERROR for one background task; before startup it means the app never came up and error-overlay.ts paints it (the async worker init is invisible to main.ts's try/catch).

The provider set (src/lightweight/)

initializeCore() takes every environment-specific capability as a provider; the browser build supplies its own for each. A new provider or provider method in core needs an implementation here, or standalone will not boot — the server-side one in apps/server/src/*_provider.ts is the pair to mirror.

Standalone-only routes (integrity checks, the LLM channel, upload handling that arrives as a buffer instead of a temp file) are registered in lightweight/browser_routes.ts; everything else is core's shared route table (adding-internal-api-route skill).