API Reference

Groundpack

Groundpack is the root facade class. boot() creates a single active runtime instance, mount() writes a MountTree into the virtual filesystem, export() returns a MountTree snapshot, fs exposes promise-based file operations, spawn() runs commands, on() subscribes to server and preview events, setPreviewScript() injects a preview script, and teardown() releases the runtime so another instance can be booted.

The returned instance exposes fs, workdir, path, export(), setPreviewScript(), spawn(), and on(). Unsupported preview helpers are not exposed.

import { Groundpack } from 'groundpack';

const container = await Groundpack.boot();
const off = container.on('server-ready', (port, url) => {
  console.log(port, url);
});
await container.mount({ 'package.json': '{}' });
await container.fs.writeFile('/src/index.js', 'console.log(1);');
console.log(await container.fs.readFile('/src/index.js', 'utf8'));
console.log(await container.export('/src'));
await container.setPreviewScript('/preview-agent.js', { type: 'module' });
const process = await container.spawn('node', ['src/index.js'], { cwd: '/' });
process.output.pipeTo(new WritableStream({ write: console.log }));
console.log(await process.exit);
console.log(container.workdir);
off();
container.teardown();

MountTree Export

container.export(path, { format: "json" }) returns a snapshot in the same MountTree shape accepted by mount(). Directories are nested objects, text files are strings, and binary files are Uint8Array values.

Only the json format is currently supported. Unsupported export options fail clearly.

const container = await Groundpack.boot();
await container.mount({ src: { 'app.js': 'export {};' } });
const snapshot = await container.export('/src', { format: 'json' });
console.log(snapshot);

FileSystemAPI

container.fs is a promise-based facade over the runtime filesystem. It supports readFile, writeFile, mkdir, readdir, rename, rm, and watch.

Sync VirtualFS methods are internal and are not part of the root package API.

const container = await Groundpack.boot();
await container.fs.mkdir('/src', { recursive: true });
await container.fs.writeFile('/src/app.js', 'export {};');
const text = await container.fs.readFile('/src/app.js', 'utf8');
const entries = await container.fs.readdir('/src');

const watcher = container.fs.watch('/src', (event, filename) => {
  console.log(event, filename);
});
watcher.close();

GroundpackProcess

container.spawn() returns a process with input, output, exit, kill(), and resize(). output combines stdout and stderr. Passing output: false keeps the stream silent while preserving the exit promise.

The current runtime supports one active spawned process per Groundpack instance.

const container = await Groundpack.boot();
await container.mount({ 'package.json': '{}', 'app.js': 'console.log(42);' });
const process = await container.spawn('node', ['app.js'], { cwd: '/' });

process.output.pipeTo(new WritableStream({
  write(chunk) {
    console.log(chunk);
  },
}));

const exitCode = await process.exit;
console.log(exitCode);

Events

container.on() subscribes to server lifecycle events and returns an unsubscribe function.

server-ready listeners receive (port, url). port listeners receive (port, type, url), where type is open or close.

const container = await Groundpack.boot();

const offReady = container.on('server-ready', (port, url) => {
  console.log(`ready ${port}`, url);
});

const offPort = container.on('port', (port, type, url) => {
  console.log(type, port, url);
});

offReady();
offPort();

Preview Hooks

setPreviewScript() injects a script tag into virtual HTML previews served from server-ready URLs. It applies to existing virtual servers and future server-ready ports.

preview-message listeners receive only messages that match the exported PreviewMessage shape.

const container = await Groundpack.boot();
await container.setPreviewScript('/preview-agent.js', { type: 'module' });

const off = container.on('preview-message', (message) => {
  console.log(message.type, message.pathname);
});

off();

PreviewMessageType

PreviewMessageType enumerates preview error message types forwarded from preview frames.

• UncaughtException
• UnhandledRejection
• ConsoleError

isPreviewMessage()

Checks whether unknown data has the shape of a Groundpack preview message.

import { isPreviewMessage } from 'groundpack';

window.addEventListener('message', (event) => {
  if (isPreviewMessage(event.data)) {
    console.log(event.data.type, event.data.pathname);
  }
});