WebContainer network proxy and external API CORS limitations

Direct Answer

WebContainers cannot bypass browser CORS restrictions. When server-side code in a WebContainer calls an external API that rejects the StackBlitz origin, the browser blocks the response and the Node.js process receives a TypeError: Failed to fetch. No WebContainer configuration, header, or flag can override this — the restriction is enforced by the browser process outside the WebAssembly sandbox.

What Happens When CORS Preflight Fails

All outbound HTTP requests from WebContainer server-side code route through the browser's native fetch/XHR stack. If the target API responds to the OPTIONS preflight without an Access-Control-Allow-Origin header matching https://stackblitz.com or the current *.webcontainer.io preview subdomain, the browser:

1. Blocks the response body from being read
2. Surfaces a network error to the calling JavaScript (opaque response if mode: 'no-cors' is used, but body remains inaccessible)
3. Logs a CORS error in DevTools Network tab with no response payload

The Node.js process sees a generic fetch failure — no status code, no headers, no body.

Confirmed Workarounds for Development Testing

1. CORS Proxy (Quickest)

Prefix the external URL with a permissive proxy that adds Access-Control-Allow-Origin: *:

// Instead of:
fetch('https://api.example.com/data')
// Use:
fetch('https://cors-anywhere.herokuapp.com/https://api.example.com/data')

Caution: Public proxies are rate-limited, may log request data, and are unsuitable for production secrets. Self-host a proxy (e.g., cors-anywhere on Railway/Render) for anything beyond quick tests.

2. Allowlist the StackBlitz Origin on the Target API

Configure the external API to return Access-Control-Allow-Origin: https://stackblitz.com (or * for development). Note: StackBlitz preview URLs change per session (https://.webcontainer.io), so wildcard or dynamic allowlisting is required.

3. Run the API Locally and Use StackBlitz Port Forwarding

Start the external API on your machine, expose it via a tunnel (ngrok, Cloudflare Tunnel, or ssh -R), then call the tunnel URL from the WebContainer. Alternatively, run the API inside the WebContainer itself (if it's a Node service) and call it via localhost: — the StackBlitz preview proxy makes this same-origin for browser-frontend code, but server-to-server calls inside the container still use localhost and avoid CORS entirely.

What Does Not Work

• Setting headers in the WebContainer fetch call — mode: 'no-cors' yields an opaque response with no body access.
• Running a local proxy inside the WebContainer (e.g., http-proxy-middleware) — that proxy still hits browser CORS when forwarding to the external API.
• Any webcontainer.config.json or package.json setting — no such configuration exists.

Verification Steps

1. Open a WebContainer terminal and run:

   node -e "fetch('https://api.example.com').then(r=>r.text()).then(console.log).catch(console.error)"

   Observe TypeError: Failed to fetch if CORS fails.
2. Check browser DevTools → Network tab: blocked requests show "CORS error" status and no response body.
3. Test a CORS proxy:

   fetch('https://cors-anywhere.herokuapp.com/https://api.example.com')

   Should succeed if the proxy allows the origin.

One Diagnostic Detail

Which external API are you calling? If it's a service you control (or have admin access to), allowlisting the StackBlitz origin is the cleanest path. If it's a third-party API without CORS configuration, a self-hosted proxy is the only reliable option.