Extensions & plugins by mode
How each Chroma plugin, host, and editor tool behaves in Portable (Web) vs Executable (Chroma Desktop), and which entry points change internals.
Chroma ships one app bundle (chroma build → dist/) that can run in a browser or inside Chroma Desktop. Public APIs stay importable in both places; internals (storage partition, reload, disk bridge) follow the runtime mode.
This section is the per-component view. Use it together with Runtime modes for vocabulary and Plugins for loader mechanics.
What counts as an "extension"
| Kind | Examples | Runs where |
|---|---|---|
| Runtime plugins | chroma-fs, chroma-router, chroma-style, chroma-t2t | Inside the app page (browser or Desktop iframe) |
| WASM engine | pkg/chroma.js, screen router, hooks | Same bundle in both modes |
| Native host | Chroma Desktop (chroma-desktop) | Executable mode only; not a chroma.json plugin |
| Editor / CLI tools | VS Code extension, @chroma/linter, chroma CLI | Developer machine; independent of deployment mode |
Entry points that change behavior
Nothing in this table replaces reading each plugin page; it lists the switches docs and code actually read.
| Entry point | Affects | Portable vs Executable |
|---|---|---|
| Host | Chroma-Fs platform detection, IndexedDB origin, iframe bridge | Browser tab vs Desktop iframe on loopback |
chroma.json → dev.desktop | Whether chroma dev opens Desktop | Develop workflow only; not baked into dist/ |
chroma.json → mode | static vs dynamic build | Same in both hosts; static apps still use plugins via plugins/loader.js |
chroma-fs.json → storage.backend | IndexedDB vs filesystem | filesystem needs Desktop bridge or Tauri; fails in a plain top-level browser tab |
plugins/loader.js + chroma.json plugins | Which plugins load | Identical contract in both modes |
bootstrapRouter({ hijackFetch }) | API router | Default true in both modes |
chroma build / WASM target | Engine binary | Always web WASM (wasm-pack --target web); Desktop loads the same artifact |
dev.hotReload / CHROMA_DEV_RELOAD | Browser reload during dev | Portable browser dev only; Desktop develop ignores auto-reload (Live reload) |
Callable ≠ identical. For example @chroma/fs writeFile resolves to IndexedDB in a typical Portable deployment and to the Desktop postMessage bridge when backend: "filesystem" and the app runs in the Desktop iframe.
Master compatibility matrix
Legend: Full — same behavior you should rely on in production. Partial — works with documented limits. Different — same API, different implementation or partition. N/A — not part of the runtime bundle.
Runtime (in the app)
| Component | Portable (Web) | Executable (Desktop) | Notes |
|---|---|---|---|
| WASM engine | Full | Full | Same chroma_bg.wasm in dist/ |
Screen router (createRouter in pkg/) | Full | Full | Hash/history inside the page or iframe |
chroma-fs | Full (default IndexedDB) | Full (default auto → filesystem when unset) | See browser plugins |
chroma-router | Full | Full | In-browser fetch hijack; no real HTTP server |
chroma-style | Full | Full | CSS injection via plugin styles hook |
chroma-t2t | Partial | Partial | In-page helpers yes; runNodeTests needs Node outside the bundle |
| Legacy libraries | Full | Full | Script tags / vendored assets; not mode-aware in CLI |
loadPlugins() | Full | Full | Fetches chroma.json + chroma.plugin.json from app origin |
Host and dev workflow
| Component | Portable (Web) | Executable (Desktop) | Notes |
|---|---|---|---|
| Chroma Desktop shell | N/A | Full | Zip import, library server, Fs bridge |
chroma dev browser live reload | Full | N/A in develop window | Use --no-desktop for reload while targeting Desktop ship |
| IndexedDB data partition | Deployment origin | Loopback origin (47823 or dev port) | Different partitions between browser dev and Desktop |
| Real files on disk | N/A (unless custom host) | Full with filesystem backend | Desktop storage |
Editor and toolchain
| Component | Portable (Web) | Executable (Desktop) | Notes |
|---|---|---|---|
| VS Code extension | N/A | N/A | Lints project; does not simulate either host |
| @chroma/linter | N/A | N/A | Same schemas and rules for all apps |
chroma validate / chroma build | N/A | N/A | Produces one dist/ for both modes |