Embedding Runnable StackBlitz Examples in Docs with WebContainers

Problem: Static code snippets don’t let readers experiment

When you write documentation or a blog post, showing a code block is useful, but readers often want to tweak the example and see the result immediately. Copy‑pasting into a local setup adds friction, and linking to a separate sandbox can break context.

Thesis: StackBlitz SDK + WebContainers gives you a runnable, forkable example that stays inside the page

StackBlitz’s WebContainers runtime compiles Node.js to WebAssembly and runs it in the same browser tab that hosts your page. Because the runtime is local, npm install and dev servers start without a round‑trip to a remote VM. The SDK lets you embed a StackBlitz project as an iframe that communicates with the parent page, so readers can edit code, run a dev server, and fork the project—all without leaving your site.

How WebContainers works (brief)

• The runtime provides a subset of Node.js APIs (fs, net, child_process, etc.) implemented in WebAssembly.
• It can execute npm install for pure‑JS packages and start tools like Vite, Next.js, or Express.
• Native modules that require node-gyp or pre‑built binaries are not supported.

Embedding via the StackBlitz SDK

The SDK exposes a function StackBlitzEmbed that mounts an iframe. The iframe must be served from a page that has cross‑origin isolation enabled (COOP and COEP headers). Without those headers the WebContainer runtime cannot allocate the necessary shared memory and will fail to boot.

// Example: adding COOP/COEP headers with a Netlify _headers file
/
  Cross-Origin-Opener-Policy: same-origin
  Cross-Origin-Embedder-Policy: require-corp

If you host the page yourself (e.g., an Express server), you can set the headers in middleware:

app.use((req, res, next) => {
  res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
  res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
  next();
});

Worked example: embedding a minimal Vite project

1. Create a public StackBlitz project (e.g., ) and note its project ID from the URL.
2. Add the StackBlitz SDK script to your page (replace YOUR_PROJECT_ID with the actual ID):

<script type="module" src="https://cdn.stackblitz.com/embed.js"></script>
<div id="stackblitz-root"></div>
<script>
  StackBlitzEmbed({
    projectId: 'YOUR_PROJECT_ID',
    container: document.getElementById('stackblitz-root'),
    height: '600px',
    view: 'preview', // or 'editor' to show the code pane
    hideNavigation: true,
    hideDevTools: false
  });
</script>

1. Serve the page with the COOP/COEP headers shown above.
2. Open the page in a modern browser (Chrome, Edge, Firefox with appropriate flags). You should see the Vite dev server start inside the iframe, and the preview pane update as you edit files.
3. To verify that nothing is hitting a remote build server, open the browser’s Network tab and confirm that requests after the initial SDK load go to stackblitz.com only for static assets; no ongoing ws or fetch calls to a cloud container appear.

Trade‑off and limitation

WebContainers cannot run packages that need native binaries (e.g., sharp, sqlite3, or any node-gyp dependency). If your example relies on such a package, the embed will fail during npm install. In that case you must fall back to a traditional cloud‑based sandbox or provide a pre‑built demo.

Adding COOP/COEP headers can affect other iframes or third‑party scripts on the same page that expect to be cross‑origin embeddable. Test that analytics widgets, ad scripts, or embedded videos still load after you apply the headers.

Actionable closing

1. Pick a small, pure‑JS project (Vite, Express, or a plain Node script) and publish it to StackBlitz.
2. Add the StackBlitz SDK embed snippet to your documentation page.
3. Serve the page with Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp headers.
4. Verify the embed boots and that the Network tab shows no persistent remote container traffic.
5. If you hit a native‑module limitation, replace the dependency with a pure‑JS alternative or link to a full‑featured sandbox instead.

By following these steps you give readers an instant, editable playground that stays within your site’s context, improving engagement and reducing the barrier to try your code.