Custom WebContainer Experience Architecture

Overview

This skill converts an IDE-like feature request into a bounded architecture. It keeps the host UI, virtual filesystem, editor models, terminal streams, runtime processes, preview frames, and persistence strategy separate so a prototype does not accidentally become an unsafe monolith.

Prerequisites

• Named user journeys and a target browser application
• A decision that a custom WebContainer experience is preferable to a StackBlitz SDK embed
• Product, licensing, security, and persistence owners for production use

Tool Discipline

Use Read, Glob, and Grep to map the host framework, editor and terminal libraries, application state, persistence, and runtime boundary. Use WebFetch only for current official StackBlitz or WebContainers documentation. Use Write or Edit only for a user-approved bounded slice.

Current Contract

• The host application owns a single lifecycle adapter; individual panes do not call boot() or teardown().
• File explorer paths are validated and normalized before virtual-filesystem operations; editor models use stable canonical paths.
• Terminal input/output is explicitly bound to one process and released on disposal.
• Preview URLs come from runtime events and are treated as untrusted application content, not trusted host UI.
• The WebContainer filesystem is not a persistence guarantee. Define an explicit save/export/versioning path before claiming durable work.
• Register error, port, and server readiness observers with bounded logging and unsubscribe ownership.

Authentication

Do not mount host secrets, auth tokens, customer .env files, or ambient browser credentials into user-controlled projects. If private packages are required, use the documented organization auth boundary and disclose which project code can access installed material.

Workflow

1. Define the smallest user journey and decide which panes and runtime capabilities it truly needs.
2. Draw ownership for host state, lifecycle adapter, filesystem, editor models, process/terminal handles, preview, and persistence.
3. Establish a typed message/event contract between panes instead of sharing raw runtime globals.
4. Implement one vertical slice: open a synthetic file, edit it, write it, run a bounded command, and display the emitted preview URL.
5. Add path-policy, process-cancellation, preview isolation, save/export, and permanent-disposal behavior.
6. Verify keyboard/accessibility behavior, HMR ownership, memory cleanup, and recovery from failed startup before expanding features.

Approval Boundaries

Require explicit approval before executing arbitrary user code, persisting or exporting user files, connecting private registries, injecting preview scripts, or enabling collaboration/telemetry. Present data flow, abuse cases, retention, and rollback first.

Output

Return the user journey, component and trust-boundary map, lifecycle and data contracts, implemented slice, verification evidence, persistence semantics, rollout stages, rollback, and open product/security decisions.

Error Handling

Examples

For an educational playground, implement one synthetic project with a file pane, editor, bounded terminal command, preview, and explicit download/export action while leaving collaboration and private packages out of scope.

Resources

• Official StackBlitz and WebContainers references
• WebContainers introduction
• Working with the filesystem