Headless bindings

React

Headless React bindings that own one runtime, start its dev server, and expose files, commands, logs, terminals, and preview state through context.

$npm i @node-sandbox/react @node-sandbox/client react

Render a preview

SandboxPreview is the shortest path from source files to a hosted preview iframe. It creates the runtime, installs dependencies, starts the dev script, and renders the listener.

import { SandboxPreview } from '@node-sandbox/react';

export function Preview() {
  return (
    <SandboxPreview
      apiKey={import.meta.env.VITE_NODESANDBOX_API_KEY}
      source={{
        type: 'files',
        files: {
          'package.json': JSON.stringify({
            scripts: { dev: 'vite --host 0.0.0.0' },
            dependencies: { vite: '8.1.3' },
          }),
          'index.html': '<h1>Hello from NodeSandbox</h1>',
        },
      }}
      iframeProps={{
        title: 'Project preview',
        style: { width: '100%', height: 600, border: 0 },
      }}
    />
  );
}

Compose with a provider

Lift SandboxProvider when multiple parts of your interface need the same runtime. Children can read the runtime with useSandbox(); the iframe can live anywhere below it.

import {
  SandboxProvider,
  SandboxIFrame,
  useSandbox,
} from '@node-sandbox/react';

function Status() {
  const { installing, loading, error, port } = useSandbox();

  if (error) return <p>{error.message}</p>;
  if (installing) return <p>Installing dependencies…</p>;
  if (loading) return <p>Starting dev server…</p>;
  return <p>Listening on {port}</p>;
}

export function Workspace({ apiKey, source }) {
  return (
    <SandboxProvider apiKey={apiKey} source={source}>
      <Status />
      <SandboxIFrame iframeProps={{ title: 'Preview' }} />
    </SandboxProvider>
  );
}

Runtime state

The hook separates install output, server output, console events, and boot state so your UI can present each phase clearly.

ValuePurpose

fsRead and edit the mirrored virtual filesystem.

commandsRun finite or background commands.

installOutputStreamed ANSI output from dependency installation.

serverOutputRaw output from the running dev process.

previewUrlPer-sandbox URL for the active listener.

restart()Clear the npm cache and recreate the runtime.

Custom lifecycle commands

The provider defaults to npm install followed by npm run dev. Override either command tuple for another package manager, script, or entry point.

<SandboxProvider
  apiKey={apiKey}
  source={source}
  installCommand={['pnpm', ['install']]}
  startCommand={['pnpm', ['run', 'preview']]}
  port={4173}
>
  <App />
</SandboxProvider>