Overview
This skill produces a repo-grounded installation and startup plan for either a custom WebContainer application or a StackBlitz SDK embed. It separates ordinary browser startup from commercial API-key configuration and organization-scoped private-package authentication.
Prerequisites
- A named browser application and permission to inspect its package and hosting configuration
- A decision between
@webcontainer/apiand@stackblitz/sdk, or evidence that both are needed - A licensing decision for production commercial use before release
Tool Discipline
Use Read, Glob, and Grep to inspect package manifests, lockfiles, browser entrypoints, headers, and existing secret bindings. Use WebFetch only for current official StackBlitz or WebContainers documentation. Use Write or Edit only after the evidence pass, and never place API keys or OAuth material in source files.
Current Contract
- Pin the package version selected by the repository's dependency policy; do not install an unreviewed moving tag.
- Call
configureAPIKeybeforeWebContainer.boot()when a commercial license supplies an API key. - Call
auth.initbefore boot when organization users need private-package access; the user must be logged in, belong to the issuing organization, and authorize the site. - Match the
Cross-Origin-Embedder-Policyresponse header to thecoepboot option. Use HTTPS outside localhost. - A StackBlitz SDK embed is a separate surface and does not require booting a custom WebContainer in the host application.
Authentication
Public prototypes may not need user authentication, but production commercial use requires a licensing review. Treat the WebContainer API key as a secret runtime binding. Treat the auth client ID and scope as configuration, initialize auth during page loading, and handle need-auth, authorized, and auth-failed explicitly. Never infer that ordinary StackBlitz login grants access to private packages.
Workflow
- Inspect the framework, package manager, lockfile, client/server boundary, CSP, and current response-header configuration.
- Choose the minimum package surface and record the installed or proposed pinned version.
- Decide whether the integration needs a commercial API key, organization auth, neither, or both.
- Configure consistent COOP/COEP headers and the matching boot option; verify the final HTML response, including cached responses.
- Add one startup module that orders API-key configuration, auth initialization, and the single boot call correctly.
- Validate in a supported desktop browser over the same origin and headers intended for deployment.
Approval Boundaries
Default to inspection and a proposed patch. Require explicit authorization before changing production headers, CSP, identity-provider settings, licensed API-key bindings, or deployment configuration. Never create, rotate, expose, or revoke a credential without a separately authorized operational step.
Output
Return the selected integration mode, package/version evidence, licensing and auth decision, header/boot contract, changed or proposed files, verification results, rollout plan, rollback, and unresolved browser or policy risks.
Error Handling
| Condition | Response |
|---|---|
| API key configured after boot | Stop and move configuration before the first boot call. |
Auth reports need-auth |
Present the user-authorized flow; do not loop or fabricate authorization. |
crossOriginIsolated is false |
Inspect actual response headers and cache behavior before changing code. |
| Integration mode is unclear | Compare custom runtime requirements with embed-only requirements before installing both SDKs. |
Examples
Given an existing Vite app, identify its lockfile and hosting headers, select a pinned WebContainer API version, document whether commercial licensing applies, and propose a single ordered startup module without reading any secret value.