StackBlitz SDK Patterns

Overview

Production patterns for the WebContainer API: singleton boot, file system CRUD, process spawning and management, jsh interactive shell, and the StackBlitz SDK for embedding projects.

Instructions

Step 1: Singleton WebContainer Instance

import { WebContainer } from '@webcontainer/api';

let instance: WebContainer | null = null;

export async function getWebContainer(): Promise<WebContainer> {
  if (!instance) {
    instance = await WebContainer.boot();
  }
  return instance;
}

// Teardown
export async function teardownWebContainer() {
  if (instance) {
    instance.teardown();
    instance = null;
  }
}

Step 2: File System Operations

const wc = await getWebContainer();

// Write file
await wc.fs.writeFile('/src/app.ts', 'export const hello = "world";');

// Read file
const content = await wc.fs.readFile('/src/app.ts', 'utf-8');

// Read directory
const entries = await wc.fs.readdir('/src', { withFileTypes: true });
entries.forEach(entry => {
  console.log(`${entry.name} (${entry.isDirectory() ? 'dir' : 'file'})`);
});

// Create directory
await wc.fs.mkdir('/src/components', { recursive: true });

// Delete file
await wc.fs.rm('/src/old.ts');

// Delete directory
await wc.fs.rm('/dist', { recursive: true });

// Watch for changes
wc.fs.watch('/src', { recursive: true }, (event, filename) => {
  console.log(`${event}: ${filename}`);
});

Step 3: Process Management

// Spawn a process
const proc = await wc.spawn('node', ['script.js']);

// Stream stdout
const reader = proc.output.getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(value);
}

// Write to stdin
const writer = proc.input.getWriter();
await writer.write('user input\n');
await writer.close();

// Wait for exit
const exitCode = await proc.exit;

// Kill a process
proc.kill();

Step 4: jsh Interactive Shell

// jsh is WebContainer's built-in shell
const jshProcess = await wc.spawn('jsh', {
  terminal: { cols: 80, rows: 24 },
});

// Connect to xterm.js
import { Terminal } from 'xterm';
const terminal = new Terminal();
terminal.open(document.getElementById('terminal')!);

jshProcess.output.pipeTo(new WritableStream({
  write(data) { terminal.write(data); },
}));

terminal.onData((data) => {
  const writer = jshProcess.input.getWriter();
  writer.write(data);
  writer.releaseLock();
});

Step 5: StackBlitz SDK (Embedding)

import sdk from '@stackblitz/sdk';

// Embed an existing project
sdk.embedProjectId('container', 'vitejs-vite-template', {
  height: 500,
  openFile: 'src/App.tsx',
  terminalHeight: 30,
});

// Embed from GitHub
sdk.embedGithubProject('container', 'user/repo', {
  openFile: 'README.md',
});

// Create new project programmatically
sdk.embedProject('container', {
  title: 'My Project',
  template: 'node',
  files: {
    'index.js': 'console.log("Hello!")',
    'package.json': '{"name":"demo","scripts":{"start":"node index.js"}}',
  },
});

Error Handling

Resources

• WebContainer API Reference
• File System Guide
• StackBlitz SDK Reference

Next Steps

Apply patterns in stackblitz-core-workflow-a.