Platform seams
One build serves the web and the desktop (ADR-0781). The seam between a page and its platform sits inside each capability package, never in an app: the package decides where the page runs, and the app uses what the capability offers.
Where the choice lives
A capability package chooses its implementation when it runs, in two steps.
- Presence, synchronously. When its module loads, the package asks
isTauri()from@tauri-apps/api/coreand makes its value: a capability a surface cannot give isnullthere (ADR-0780). - The desktop implementation, in its asynchronous step. The desktop
code loads with
import()when the page connects or the capability first acts (ADR-0778), so a browser's first load holds none of it.
| Package | In a browser | In a Tauri window, loaded when |
|---|---|---|
@epicenter/local (settings) |
localStorage |
AppData through the shell: its first read, write or watch |
@epicenter/folder (home) |
the account's repository | the data folder: the folder opens |
@epicenter/account (connectAccount) |
browser OAuth | the shell's sign-in; its relay with the first request |
@epicenter/ai (customEndpoints, localServers) |
the page's fetch and key |
the shell's key and fetch: the first request |
@epicenter/recorder (recorder) |
the page's microphone | the shell's recorder: the first call |
@epicenter/transcription (localSpeech) |
null |
the generated bindings: the first call |
A capability with a synchronous read takes it from the settings store, or
imports its small desktop part directly. @epicenter/account's tauri.ts
is the one such part: it reads who is signed in from account.json at
once, and asks the shell only when the person acts.
What an app does
An app has no #platform/* imports, no tauri condition, and no build
per surface. src/lib/app.ts makes every capability once, synchronously,
and the views branch on what each offers:
{#if shortcut}<ShortcutSettings {shortcut} />{/if}
{#if folder.reveal === null}<RepositoryChrome />{:else}<FolderChrome />{/if}
- Branch on a capability, never on the platform.
folder.revealis there for a folder on this computer;shortcutandspeecharenullin a browser. App code does not callisTauri(); an app-owned capability may, in the module that makes it (Whispering'ssrc/lib/shortcut.ts), with its desktop code behindimport(). - A view only some surfaces show is its own component under the
branch (
ShortcutSettings,SpeechSettings,FolderSettings), and imports only what the page may load at once. - Words that differ by surface follow the same branch: Vocab's
accountPurposereadsfolder.reveal.
Tests and the test condition
The test export condition stays
(ADR-0787):
under --conditions=test, @epicenter/folder's root is a folder in memory
and @epicenter/local's is settings in memory. A test of desktop behavior
mocks isTauri (mock.module('@tauri-apps/api/core', ...)) and the
desktop module it loads.
scripts/first-load.test.ts builds every page source of each app with a
desktop window (firstLoadModules from
@epicenter/vite-config/module-graph) and fails when what loads before any
import() holds a Tauri plugin, the shell's API beyond core, or a
package's desktop implementation. Add a new desktop module's name to its
DESKTOP patterns when it does not match them.
The desktop shell's build
A desktop app's src-tauri/tauri.conf.json loads ../build, the output
the web serves, and builds it first ("beforeBuildCommand": "bun run build"). tauri.dev.conf.json loads the app's dev server (devUrl),
which tauri dev starts ("beforeDevCommand": "bun run dev"). One
svelte-check typechecks every surface.
Anti-patterns
- A static import of a desktop module on a page's path: the web's first
load carries it. Load it with
import()in the capability's asynchronous step. - A
tauriexport condition, animportsseam, or a second build or tsconfig per surface. - An app asking where it runs to pick a capability or a store;
homeandconnectAccountpick. - A capability that answers a fake on a surface that lacks it, instead of
null. - Choosing the store anywhere but
home, or moving files between stores.