---

name: stackblitz-hello-world description: >- Build a minimal, controlled WebContainer smoke test that boots once, mounts a small project, observes process exit, and captures the preview URL. Use when proving browser/runtime compatibility before building a larger in-browser development experience. Trigger with "StackBlitz hello world", "test WebContainers", or "run Node in the browser". argument-hint: "[project-path] [entrypoint]" allowed-tools: Read, Glob, Grep, WebFetch, Write, Edit version: 1.7.0 author: Jeremy Longshore jeremy@intentsolutions.io license: MIT tags:

• saas
• stackblitz
• webcontainers
• quickstart model: inherit effort: medium compatibility: Designed for Claude Code

---

WebContainer Controlled Smoke Test

Overview

This skill adds or plans the smallest useful WebContainer proof: one instance, one deterministic file tree, one bounded dependency install, one server process, and one preview readiness observation. It avoids presenting a tutorial snippet as a production architecture.

Prerequisites

• A browser application already passing the StackBlitz integration preflight
• Cross-origin isolation and HTTPS behavior verified for the target environment
• A small synthetic project that contains no proprietary source or secrets

Tool Discipline

Use Read, Glob, and Grep to establish the application entrypoint, package versions, and existing lifecycle ownership. Use WebFetch only for current official StackBlitz or WebContainers documentation. Use Write or Edit for a user-requested smoke-test implementation after inspection.

Current Contract

• WebContainer.boot() is expensive and permits only one concurrent instance; centralize ownership.
• mount() accepts a FileSystemTree or supported binary snapshot and copies it into the virtual filesystem.
• Check a spawned install process through its exit promise before starting the server.
• Register server-ready, error, and cleanup handlers before relying on a preview URL; retain the unsubscribe functions.
• Use the URL emitted by server-ready rather than constructing a preview host.

Authentication

The smoke test must not contain API keys, registry tokens, cookies, or .env data. If commercial API-key configuration or organization auth is required, consume the existing runtime binding and initialization module without displaying its value or duplicating the flow.

Workflow

1. Confirm the current package and browser support assumptions from repository evidence.
2. Reuse or create a singleton owner for the WebContainer instance.
3. Define a tiny synthetic project with a locked dependency set and explicit start script.
4. Mount the tree, spawn the repository-approved install command, stream bounded status output, and fail on a nonzero exit.
5. Subscribe to readiness and error events, start the server, and attach the emitted URL to the intended preview element.
6. Record cleanup behavior for listeners, processes, and teardown() when the owning view is permanently disposed.

Approval Boundaries

Do not add arbitrary user source, private packages, production secrets, telemetry, or broad network access to the smoke test without explicit authorization and a security review. Do not alter production isolation headers merely to make a local example pass.

Output

Return the exact test surface, package and header evidence, lifecycle owner, expected state sequence, bounded logs, preview readiness result, cleanup path, and any environment-specific limitation.

Error Handling

Condition	Response
A second boot path exists	Stop and consolidate lifecycle ownership before testing.
Install exits nonzero	Preserve the exit code and bounded output; do not blindly retry.
Preview never becomes ready	Check process exit and port/error events before changing ports.
Test needs real customer code	Replace it with a synthetic fixture and report the missing contract separately.

Examples

For a Vite host, mount a two-file synthetic Node project, wait for a successful install exit, start its server, and verify the server-ready URL in one supported browser without committing any generated dependency tree.

Resources

• Official StackBlitz and WebContainers references
• WebContainers quickstart
• WebContainer API reference