WebContainer API is a browser-based runtime for executing Node.js applications and operating system commands. It enables you to build applications that previously required a server running.
WebContainer API is perfect for building interactive coding experiences. Among its most common use cases are production-grade IDEs, programming tutorials, or employee onboarding platforms.
For an up-to-date documentation, please refer to our documentation.
WebContainer requiresSharedArrayBuffer to function. In turn, this requires your website to be cross-origin isolated. Among other things, the root document must be served with:
Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin
You can check our article on the subject and our docs on browser support for more details.
Please note that your deployed page must be served over HTTPS. This is not necessary when developing locally, as localhost is exempt from some browser restrictions, but there is no way around it once you deploy to production.
Check the WebContainer API demo app.
Here's an example main.ts file:
import{WebContainer}from"@webcontainer/api";constfiles: FileSystemTree={"index.js": {file: {contents: "",},},};letwebcontainer: WebContainer;// add a textarea (the editor) and an iframe (a preview window) to the documentdocument.querySelector("#app").innerHTML=` <div class="container"> <div class="editor"> <textarea>I am a textarea</textarea> </div> <div class="preview"> <iframe></iframe> </div> </div>`;// the editorconsttextarea=document.querySelector("textarea");// the preview windowconstiframe=document.querySelector("iframe");window.addEventListener("load",async()=>{textarea.value=files["index.js"].file.contents;textarea.addEventListener("input",(event)=>{constcontent=event.currentTarget.value;webcontainer.fs.writeFile("/index.js",content);});// call only oncewebcontainer=awaitWebContainer.boot();awaitwebcontainer.mount(files);constexitCode=awaitinstallDependencies();if(exitCode!==0){thrownewError("Installation failed");}startDevServer();});asyncfunctioninstallDependencies(){// install dependenciesconstinstallProcess=awaitwebcontainer.spawn("npm",["install"]);installProcess.output.pipeTo(newWritableStream({write(data){console.log(data);},}));// wait for install command to exitreturninstallProcess.exit;}asyncfunctionstartDevServer(){// run `npm run start` to start the express appawaitwebcontainer.spawn("npm",["run","start"]);// wait for `server-ready` eventwebcontainer.on("server-ready",(port,url)=>{iframe.src=url;});}Cookie blockers, either from third-party addons or built-in into the browser, can prevent WebContainer from running correctly. Check the on('error') event and our docs.
To troubleshoot other problems, check the Troubleshooting page in our docs.
Copyright 2023 StackBlitz, Inc.