StackBlitz Debug Bundle

Overview

Collect WebContainer diagnostic info: boot state, file system, process list.

Instructions

Step 1: Check Boot State

async function diagnoseWebContainer(wc: WebContainer) {
  const report: Record<string, any> = {};

  // File system check
  try {
    const entries = await wc.fs.readdir('/');
    report.filesystem = { status: 'ok', rootEntries: entries.length };
  } catch (e: any) {
    report.filesystem = { status: 'error', message: e.message };
  }

  // Node.js check
  try {
    const proc = await wc.spawn('node', ['-e', 'console.log(JSON.stringify({version: process.version, arch: process.arch}))']);
    let output = '';
    proc.output.pipeTo(new WritableStream({ write(data) { output += data; } }));
    await proc.exit;
    report.node = JSON.parse(output);
  } catch (e: any) {
    report.node = { status: 'error', message: e.message };
  }

  // Memory check
  try {
    const proc = await wc.spawn('node', ['-e', 'console.log(JSON.stringify(process.memoryUsage()))']);
    let output = '';
    proc.output.pipeTo(new WritableStream({ write(data) { output += data; } }));
    await proc.exit;
    report.memory = JSON.parse(output);
  } catch { report.memory = 'unavailable'; }

  return report;
}

Step 2: Check Browser Support

function checkBrowserSupport() {
  return {
    sharedArrayBuffer: typeof SharedArrayBuffer !== 'undefined',
    crossOriginIsolated: window.crossOriginIsolated,
    serviceWorker: 'serviceWorker' in navigator,
    userAgent: navigator.userAgent,
  };
}

Error Handling

Resources

• WebContainer API Reference
• Browser Support

Next Steps

For resource limits, see stackblitz-rate-limits.

StackBlitz Deploy Integration

Overview

Deploy WebContainer apps to Vercel, Netlify with proper COOP/COEP headers.

Instructions

Refer to the WebContainer API documentation for detailed guidance.

See the core workflow skills for implementation patterns.

Error Handling

Resources

• WebContainer API Docs
• StackBlitz SDK

Next Steps

See related skills for more patterns.

StackBlitz Hello World

Overview

Boot a WebContainer, mount a file system tree, install dependencies with npm, and start a dev server -- all running inside the browser tab. No backend server needed.

Prerequisites

• @webcontainer/api installed (see stackblitz-install-auth)
• Cross-origin isolation headers configured
• Modern browser (Chrome 90+, Firefox 90+, Safari 16.4+)

Instructions

Step 1: Define File System Tree

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

const files: FileSystemTree = {
  'package.json': {
    file: {
      contents: JSON.stringify({
        name: 'wc-hello',
        scripts: { start: 'node index.js', dev: 'nodemon index.js' },
        dependencies: { express: '^4.18.0' },
      }),
    },
  },
  'index.js': {
    file: {
      contents: `
const express = require('express');
const app = express();
app.get('/', (req, res) => res.send('Hello from WebContainer!'));
app.listen(3000, () => console.log('Server running on port 3000'));
      `.trim(),
    },
  },
  src: {
    directory: {
      'utils.js': { file: { contents: 'module.exports = { greet: (n) => "Hello " + n };' } },
    },
  },
};

Step 2: Boot and Mount

const wc = await WebContainer.boot();
await wc.mount(files);

console.log('Files mounted. Installing dependencies...');

Step 3: Install Dependencies

const installProcess = await wc.spawn('npm', ['install']);

// Stream install output
installProcess.output.pipeTo(new WritableStream({
  write(data) { console.log(data); },
}));

const installCode = await installProcess.exit;
if (installCode !== 0) throw new Error(`npm install failed: exit ${installCode}`);
console.log('Dependencies installed.');

Step 4: Start Dev Server

const serverProcess = await wc.spawn('npm', ['start']);

serverProcess.output.pipeTo(new WritableStream({
  write(data) { console.log(data); },
}));

// Listen for server-ready event
wc.on('server-ready', (port, url) => {
  console.log(`Server ready at ${url} (port ${port})`);
  // Display in iframe
  document.querySelector('iframe')!.src = url;
});

Output

added 57 packages in 3s
Dependencies installed.
Server running on port 3000
Server ready at https://xxx.webcontainer.io (port 3000)

Error Handling

npm install @webcontainer/api

npm install @stackblitz/sdk

// Express middleware
app.use((req, res, next) => {
  res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
  res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
  next();
});

// Vite config
export default defineConfig({
  server: {
    headers: {
      'Cross-Origin-Embedder-Policy': 'require-corp',
      'Cross-Origin-Opener-Policy': 'same-origin',
    },
  },
});

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

const wc = await WebContainer.boot();
console.log('WebContainer booted successfully');

// Verify filesystem works
await wc.mount({ 'test.txt': { file: { contents: 'Hello WebContainers!' } } });
const content = await wc.fs.readFile('/test.txt', 'utf-8');
console.log(`File content: ${content}`);

WebContainer booted successfully
File content: Hello WebContainers!

Resources

• WebContainer API Docs
• WebContainer Quickstart
• StackBlitz SDK

Next Steps

Proceed to stackblitz-hello-world for your first WebContainer project.

StackBlitz Local Dev Loop

Overview

Set up a Vite-based development environment for WebContainer applications with cross-origin headers, hot module replacement, and Vitest for testing file system operations.

Instructions

Step 1: Vite Project with WebContainers

npm create vite@latest wc-app -- --template vanilla-ts
cd wc-app
npm install @webcontainer/api

Step 2: Configure Vite Headers

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  server: {
    headers: {
      'Cross-Origin-Embedder-Policy': 'require-corp',
      'Cross-Origin-Opener-Policy': 'same-origin',
    },
  },
});

Step 3: Test WebContainer Operations

// tests/webcontainer.test.ts
import { describe, it, expect } from 'vitest';

// Note: WebContainer tests require a browser environment
// Use Playwright for full integration tests
describe('FileSystemTree Builder', () => {
  it('creates valid tree from flat paths', () => {
    const tree = buildFileTree({
      'src/index.ts': 'console.log("hello")',
      'package.json': '{"name":"test"}',
    });
    expect(tree['package.json']).toHaveProperty('file');
    expect(tree.src).toHaveProperty('directory');
  });
});

function buildFileTree(flatFiles: Record<string, string>) {
  const tree: any = {};
  for (const [path, contents] of Object.entries(flatFiles)) {
    const parts = path.split('/');
    let current = tree;
    for (let i = 0; i < parts.length - 1; i++) {
      if (!current[parts[i]]) current[parts[i]] = { directory: {} };
      current = current[parts[i]].directory;
    }
    current[parts[parts.length - 1]] = { file: { contents } };
  }
  return tree;
}

Error Handling

Resources

• Vite Config
• WebContainer Guides

Next Steps

Proceed to stackblitz-sdk-patterns for production patterns.

StackBlitz Performance Tuning

Overview

Optimize WebContainer boot time, file system mounts, and process spawning.

Instructions

Refer to the WebContainer API documentation for detailed guidance.

See the core workflow skills for implementation patterns.

Error Handling

Resources

• WebContainer API Docs
• StackBlitz SDK

Next Steps

See related skills for more patterns.

StackBlitz Prod Checklist

Overview

Production checklist for WebContainer apps: headers, browser support, fallbacks.

Instructions

Refer to the WebContainer API documentation for detailed guidance.

See the core workflow skills for implementation patterns.

Error Handling

Resources

• WebContainer API Docs
• StackBlitz SDK

Next Steps

See related skills for more patterns.

StackBlitz Rate Limits

Overview

WebContainer resource limits: memory, CPU, file system size, process count.

Instructions

Step 1: WebContainer Resource Limits

Step 2: Handle Memory Pressure

// Monitor memory usage inside WebContainer
const proc = await wc.spawn('node', ['-e', `
  setInterval(() => {
    const mem = process.memoryUsage();
    const mbUsed = Math.round(mem.heapUsed / 1024 / 1024);
    if (mbUsed > 500) console.warn('High memory: ' + mbUsed + 'MB');
  }, 5000);
`]);

Step 3: Optimize File System Size

// Mount only essential files -- skip test files, docs, etc.
const productionFiles: FileSystemTree = {
  'package.json': { file: { contents: minimalPackageJson } },
  src: { directory: { /* only source files */ } },
  // Skip: tests/, docs/, .git/, large assets
};
await wc.mount(productionFiles);

Error Handling

Resources

• WebContainer Guides

Next Steps

For security, see stackblitz-security-basics.

StackBlitz Reference Architecture

Overview

Production architecture for WebContainer-powered browser IDEs and playgrounds.

Instructions

Refer to the WebContainer API documentation for detailed guidance.

See the core workflow skills for implementation patterns.

Error Handling

Resources

• WebContainer API Docs
• StackBlitz SDK

Next Steps

See related skills for more patterns.

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', &