# WebContainer Guide: Running Node.js Apps in the Browser WebContainer is a revolutionary technology that allows you to run Node.js applications directly in the browser using WebAssembly. This guide covers everything you need to know about implementing WebContainers in your web applications. ## What is WebContainer? WebContainer is a browser-based runtime for executing Node.js applications and operating system commands. It provides: - **Full Node.js Runtime**: Complete Node.js environment in the browser - **File System**: Virtual file system with read/write capabilities - **Package Management**: npm/yarn support for installing dependencies - **Process Management**: Spawn and manage processes - **Network Access**: HTTP requests and server capabilities - **Terminal Emulation**: Interactive command-line interface ### Key Benefits - **No Server Required**: Run Node.js apps entirely client-side - **Instant Setup**: No installation or configuration needed - **Security**: Sandboxed environment with controlled access - **Performance**: Near-native execution speed - **Compatibility**: Works with most Node.js applications ## Prerequisites ### Browser Requirements WebContainer requires modern browsers with support for: - **SharedArrayBuffer**: Essential for WebAssembly threading - **Cross-Origin Isolation**: Required for SharedArrayBuffer access - **WebAssembly**: For running the Node.js runtime - **Service Workers**: For file system operations ### Server Configuration Your web server must serve pages with these headers: ```http Cross-Origin-Embedder-Policy: require-corp Cross-Origin-Opener-Policy: same-origin ``` ### Development Environment - Node.js 16+ (for development tooling) - Modern bundler (Vite, Webpack, etc.) - TypeScript support (recommended) ## Installation Install the WebContainer API package: ```bash npm install @webcontainer/api ``` For TypeScript projects, types are included in the package. ## Basic Setup ### 1. HTML Configuration Ensure your HTML includes the required headers: ```html WebContainer App

``` ### 2. Basic WebContainer Service ```typescript import { WebContainer } from '@webcontainer/api'; export class WebContainerService { private instance: WebContainer | null = null; async boot(): Promise { if (this.instance) { return this.instance; } // Check Cross-Origin Isolation if (!crossOriginIsolated) { throw new Error( 'WebContainer requires Cross-Origin Isolation. ' + 'Please ensure proper headers are set.' ); } try { this.instance = await WebContainer.boot(); return this.instance; } catch (error) { throw new Error(`Failed to boot WebContainer: ${error.message}`); } } async teardown(): Promise { if (this.instance) { await this.instance.teardown(); this.instance = null; } } } ``` ## Core Concepts ### File System Tree WebContainer uses a tree structure to represent files and directories: ```typescript import type { FileSystemTree } from '@webcontainer/api'; const files: FileSystemTree = { 'package.json': { file: { contents: JSON.stringify({ name: 'my-app', scripts: { dev: 'vite', build: 'vite build' }, dependencies: { 'react': '^18.2.0' } }, null, 2) } }, 'src': { directory: { 'main.js': { file: { contents: `console.log('Hello WebContainer!');` } } } } }; ``` ### Process Management WebContainer can spawn and manage processes: ```typescript // Install dependencies const installProcess = await webContainer.spawn('npm', ['install']); await installProcess.exit; // Start development server const devProcess = await webContainer.spawn('npm', ['run', 'dev']); // Listen to output devProcess.output.pipeTo(new WritableStream({ write(data) { console.log('Process output:', data); } })); ``` ### File Operations Read and write files in the virtual file system: ```typescript // Write a file await webContainer.fs.writeFile('/src/app.js', 'console.log("Hello!");'); // Read a file const contents = await webContainer.fs.readFile('/src/app.js', 'utf-8'); // Create directory await webContainer.fs.mkdir('/src/components', { recursive: true }); ``` ## Implementation Guide ### Step 1: Create WebContainer Service ```typescript import { WebContainer } from '@webcontainer/api'; import type { FileSystemTree } from '@webcontainer/api'; export class WebContainerService { private instance: WebContainer | null = null; private bootPromise: Promise | null = null; async boot(): Promise { if (this.instance) return this.instance; if (this.bootPromise) return this.bootPromise; if (!crossOriginIsolated) { throw new Error('Cross-Origin Isolation required'); } this.bootPromise = WebContainer.boot(); this.instance = await this.bootPromise; return this.instance; } async mountFiles(files: FileSystemTree): Promise { if (!this.instance) throw new Error('WebContainer not initialized'); await this.instance.mount(files); } async installDependencies(): Promise { if (!this.instance) throw new Error('WebContainer not initialized'); const installProcess = await this.instance.spawn('npm', ['install']); const exitCode = await installProcess.exit; if (exitCode !== 0) { throw new Error(`npm install failed with exit code ${exitCode}`); } } async startDevServer(): Promise { if (!this.instance) throw new Error('WebContainer not initialized'); const devProcess = await this.instance.spawn('npm', ['run', 'dev']); // Wait for server to be ready return new Promise((resolve, reject) => { const timeout = setTimeout(() => { reject(new Error('Server startup timeout')); }, 30000); const reader = devProcess.output.getReader(); const readOutput = async () => { try { while (true) { const { value, done } = await reader.read(); if (done) break; console.log('Dev server output:', value); // Detect server ready if (value.includes('localhost:') || value.includes('Local:')) { const match = value.match(/localhost:(\d+)/); if (match) { clearTimeout(timeout); resolve(`http://localhost:${match[1]}`); break; } } } } catch (error) { clearTimeout(timeout); reject(error); } }; readOutput(); }); } } ``` ### Step 2: Create Project Templates ```typescript export interface ProjectTemplate { id: string; name: string; description: string; files: FileSystemTree; scripts: Record; ports: number[]; } export const reactTemplate: ProjectTemplate = { id: 'react-vite', name: 'React + Vite', description: 'React application with Vite build tool', files: { 'package.json': { file: { contents: JSON.stringify({ name: 'react-app', private: true, version: '0.0.0', type: 'module', scripts: { dev: 'vite', build: 'vite build', preview: 'vite preview' }, dependencies: { react: '^18.2.0', 'react-dom': '^18.2.0' }, devDependencies: { '@vitejs/plugin-react': '^4.2.1', vite: '^5.0.8' } }, null, 2) } }, 'index.html': { file: { contents: ` React App

` } }, 'vite.config.js': { file: { contents: `import { defineConfig } from 'vite' import react from '@vitejs/plugin-react' export default defineConfig({ plugins: [react()], server: { host: true, port: 5173 } })` } }, src: { directory: { 'main.jsx': { file: { contents: `import { StrictMode } from 'react' import { createRoot } from 'react-dom/client' import App from './App.jsx' createRoot(document.getElementById('root')).render( , )` } }, 'App.jsx': { file: { contents: `import { useState } from 'react' function App() { const [count, setCount] = useState(0) return (

Hello WebContainer!

) } export default App` } } } } }, scripts: { dev: 'vite', build: 'vite build' }, ports: [5173] }; ``` ### Step 3: React Hook Integration ```typescript import { useCallback, useEffect, useState } from 'react'; import { WebContainerService } from '../services/webcontainer'; export function useWebContainer() { const [status, setStatus] = useState<'idle' | 'booting' | 'ready' | 'error'>('idle'); const [error, setError] = useState(null); const [previewUrl, setPreviewUrl] = useState(null); const webContainerService = new WebContainerService(); const bootContainer = useCallback(async () => { if (status === 'booting' || status === 'ready') return; try { setStatus('booting'); setError(null); await webContainerService.boot(); setStatus('ready'); } catch (err) { setError(err instanceof Error ? err.message : 'Unknown error'); setStatus('error'); } }, [status]); const loadTemplate = useCallback(async (template: ProjectTemplate) => { try { setStatus('booting'); setError(null); await webContainerService.boot(); await webContainerService.mountFiles(template.files); await webContainerService.installDependencies(); if (template.ports.length > 0) { const url = await webContainerService.startDevServer(); setPreviewUrl(url); } setStatus('ready'); } catch (err) { setError(err instanceof Error ? err.message : 'Failed to load template'); setStatus('error'); } }, []); const writeFile = useCallback(async (path: string, contents: string) => { await webContainerService.writeFile(path, contents); }, []); const readFile = useCallback(async (path: string): Promise => { return await webContainerService.readFile(path); }, []); return { status, error, previewUrl, bootContainer, loadTemplate, writeFile, readFile, isReady: status === 'ready', isLoading: status === 'booting' }; } ``` ## Advanced Features ### Terminal Integration ```typescript export class TerminalService { private webContainer: WebContainer; constructor(webContainer: WebContainer) { this.webContainer = webContainer; } async executeCommand(command: string, args: string[] = []): Promise { const process = await this.webContainer.spawn(command, args); // Stream output to terminal UI process.output.pipeTo(new WritableStream({ write(data) { // Send to terminal component this.onOutput?.(data); } })); return process.exit; } onOutput?: (data: string) => void; } ``` ### File Explorer ```typescript export async function getFileTree(webContainer: WebContainer, path = '/'): Promise { const entries = await webContainer.fs.readdir(path, { withFileTypes: true }); return Promise.all( entries.map(async (entry) => { const fullPath = `${path}/${entry.name}`.replace('//', '/'); if (entry.isDirectory()) { return { name: entry.name, path: fullPath, type: 'directory', children: await getFileTree(webContainer, fullPath) }; } else { return { name: entry.name, path: fullPath, type: 'file' }; } }) ); } ``` ### Live Preview ```typescript export function PreviewFrame({ url }: { url: string | null }) { if (!url) { return

No preview available

; } return (

Code Stories

Code Stories