Targ Apps Docs
Chroma

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"

KindExamplesRuns where
Runtime pluginschroma-fs, chroma-router, chroma-style, chroma-t2tInside the app page (browser or Desktop iframe)
WASM enginepkg/chroma.js, screen router, hooksSame bundle in both modes
Native hostChroma Desktop (chroma-desktop)Executable mode only; not a chroma.json plugin
Editor / CLI toolsVS Code extension, @chroma/linter, chroma CLIDeveloper 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 pointAffectsPortable vs Executable
HostChroma-Fs platform detection, IndexedDB origin, iframe bridgeBrowser tab vs Desktop iframe on loopback
chroma.json → dev.desktopWhether chroma dev opens DesktopDevelop workflow only; not baked into dist/
chroma.json → modestatic vs dynamic buildSame in both hosts; static apps still use plugins via plugins/loader.js
chroma-fs.json → storage.backendIndexedDB vs filesystemfilesystem needs Desktop bridge or Tauri; fails in a plain top-level browser tab
plugins/loader.js + chroma.json pluginsWhich plugins loadIdentical contract in both modes
bootstrapRouter({ hijackFetch })API routerDefault true in both modes
chroma build / WASM targetEngine binaryAlways web WASM (wasm-pack --target web); Desktop loads the same artifact
dev.hotReload / CHROMA_DEV_RELOADBrowser reload during devPortable 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)

ComponentPortable (Web)Executable (Desktop)Notes
WASM engineFullFullSame chroma_bg.wasm in dist/
Screen router (createRouter in pkg/)FullFullHash/history inside the page or iframe
chroma-fsFull (default IndexedDB)Full (default auto → filesystem when unset)See browser plugins
chroma-routerFullFullIn-browser fetch hijack; no real HTTP server
chroma-styleFullFullCSS injection via plugin styles hook
chroma-t2tPartialPartialIn-page helpers yes; runNodeTests needs Node outside the bundle
Legacy librariesFullFullScript tags / vendored assets; not mode-aware in CLI
loadPlugins()FullFullFetches chroma.json + chroma.plugin.json from app origin

Host and dev workflow

ComponentPortable (Web)Executable (Desktop)Notes
Chroma Desktop shellN/AFullZip import, library server, Fs bridge
chroma dev browser live reloadFullN/A in develop windowUse --no-desktop for reload while targeting Desktop ship
IndexedDB data partitionDeployment originLoopback origin (47823 or dev port)Different partitions between browser dev and Desktop
Real files on diskN/A (unless custom host)Full with filesystem backendDesktop storage

Editor and toolchain

ComponentPortable (Web)Executable (Desktop)Notes
VS Code extensionN/AN/ALints project; does not simulate either host
@chroma/linterN/AN/ASame schemas and rules for all apps
chroma validate / chroma buildN/AN/AProduces one dist/ for both modes

Where to read more

On this page