Skip to content
Ask
Overview

@inbrowser/workspace

Browser-native workspace runtime: OPFS/memory files, esbuild preview compilation, jailed browser shell, isomorphic-git, package import maps, and optional agent tool adapters.

@inbrowser/workspace is the browser-native workspace runtime for the inbrowser stack. It gives an app or agent a local project space without promising a full browser Node process.

The package owns infrastructure:

  • a workspace file system over OPFS, with an in-memory fallback
  • scoped workspaces so /work can map to isolated browser storage
  • React/TSX preview compilation through esbuild-wasm
  • host-module aliases so preview code uses the app’s React runtime
  • a jailed browser shell over the workspace file system
  • persisted workspace snapshots for local restore points
  • structured local git operations through browser-native Git-shaped objects
  • a browser package registry that writes import maps for preview compilation
  • optional thin agent-tool adapters

The package does not own prompting, model selection, UI, product copy, or app-builder workflow. Those belong to the host application.

Why It Exists

Running a real Vite dev server in a browser runtime is fragile. The reliable browser-native shape is different: write files into a virtual workspace, compile the entry module with esbuild-wasm, mount the result with host runtime modules, and expose shell/git/package operations as structured workspace services.

That is the contract this package provides.

Basic Shape

TS
import { createBrowserWorkspace } from '@inbrowser/workspace';

const workspace = await createBrowserWorkspace({
  id: 'local-project',
  root: '/work',
  storage: 'opfs-with-memory-fallback',
});

await workspace.fs.promises.writeFile(
  '/work/src/App.tsx',
  'export default function App() { return <h1>Hello</h1>; }',
);

const shell = await workspace.createShell();
const git = await workspace.createGit();
const beforeEdit = await workspace.snapshots.create({ label: 'before edit' });

Preview, shell, and git are loaded lazily. Importing the package root does not pull esbuild-wasm or just-bash until the corresponding service is requested. Snapshots are local restore points for the working tree. Git is explicit project history. Restoring a snapshot rewrites workspace files but preserves .git.

Documentation