WebContainer COOP/COEP Header Requirements for CDN-Hosted Low-Traffic Projects

Question

Header Configuration for Self-Hosted WebContainer Environments

StackBlitz WebContainers enable client-side Node.js execution through WebAssembly, shifting compute costs to the browser. For low-traffic workloads, hosting static project files on a CDN eliminates persistent server infrastructure. However, the WebContainer runtime requires Cross-Origin-Embedder-Policy (COEP) and Cross-Origin-Opener-Policy (COOP) headers to enable SharedArrayBuffer, which is essential for the virtualized POSIX environment.

CDN Header Propagation Constraints

Many CDN providers either strip custom headers by default or require specific configuration to propagate COEP: require-corp and COOP: same-origin across all responses. The WebContainer boot process also initiates cross-origin requests to the StackBlitz API for environment metadata, creating a tension between the strict header requirements and typical CDN caching behaviors.

Unresolved Configuration Boundary

The documentation specifies header requirements for the primary document but does not clarify whether subresource requests (WebAssembly modules, worker scripts, API calls) must carry identical headers or if the initial document headers are sufficient for the entire WebContainer lifecycle.

Which specific responses must include COEP/COOP headers when serving WebContainer applications from a CDN?
Can the headers be applied only to the entry HTML document, or must they propagate to all WebAssembly and API responses?

Tasadduq Burney · Answer

Header Requirements for WebContainer Isolation

To enable SharedArrayBuffer required by StackBlitz WebContainers, only the top-level document that boots the runtime needs Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy. Confirmed fact: the browser creates a cross-origin isolated context from the entry HTML headers. Once isolated, the WebContainer lifecycle runs in that context.

What must carry COOP/COEP

Confirmed: the primary HTML document must return Cross-Origin-Opener-Policy: same-origin or same-origin-allow-popups and Cross-Origin-Embedder-Policy: require-corp. Applying these to the entry HTML is sufficient for the entire WebContainer session; COOP/COEP do not need to be repeated on WebAssembly modules, worker scripts, or API responses.

Likely explanation: subresources are loaded under the isolated context. With COEP: require-corp active, the browser blocks any cross-origin embeddable resource that does not opt-in. Therefore WASM/workers from another origin need Cross-Origin-Resource-Policy and CORS, not COOP/COEP.

Steps for CDN-hosted low-traffic projects

Configure the CDN to inject COOP and COEP only on the entry HTML response, e.g., index.html. Ensure the CDN does not strip these headers from cached HTML.
Serve same-origin static assets from the same CDN origin as the HTML when possible. If WASM or workers are cross-origin, ensure they return Access-Control-Allow-Origin matching the page origin and Cross-Origin-Resource-Policy: cross-origin or same-origin as appropriate.
Do not apply COOP/COEP to API responses, including StackBlitz metadata APIs. Those endpoints need standard CORS headers only.

Verification: open console and check self.crossOriginIsolated is true, and Network tab shows COOP/COEP on HTML only.

One missing diagnostic detail that changes recommendation: are your WebAssembly modules and worker scripts served from the same CDN domain and path as the entry HTML, or from a separate origin?

WebContainer COOP/COEP Header Requirements for CDN-Hosted Low-Traffic Projects

Header Configuration for Self-Hosted WebContainer Environments

CDN Header Propagation Constraints

Unresolved Configuration Boundary

1 answer

Header Requirements for WebContainer Isolation

What must carry COOP/COEP

Steps for CDN-hosted low-traffic projects

Your perspective belongs here.

0 question comments