WebContainer API Starter

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.

How To

For an up-to-date documentation, please refer to our documentation.

Cross-Origin Isolation

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.

Serve over HTTPS

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.

Demo

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;});}

Troubleshooting

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.

Adapting for Cloudflare Workers

To adapt this project for Cloudflare Workers, follow these steps:

1. Convert the Application to a Serverless Function:

   • Cloudflare Workers run serverless functions, so you'll need to convert your application into a function that can be executed by Cloudflare Workers. This typically involves creating a worker.js file that exports a fetch event handler.

2. Install Wrangler:

   • Install the Cloudflare Wrangler CLI by running npm install -g @cloudflare/wrangler.

3. Initialize a Wrangler Project:

   • Run wrangler init to create a new Wrangler project. Follow the prompts to set up your project.

4. Write the Worker Script:

   • Create a worker.js file with the following content:

     exportdefault{asyncfetch(request){// Your serverless function logic herereturnnewResponse("Hello from Cloudflare Workers!",{headers: {"content-type": "text/plain"},});},};

5. Configure Wrangler:

   • Update the wrangler.toml file with your Cloudflare account details and other configurations.

6. Deploy the Worker:

   • Run wrangler publish to deploy your worker to Cloudflare.

License

Copyright 2023 StackBlitz, Inc.

How to Use This Template

To use this template, follow these steps:

1. Fork the Repository:

   • Click the "Fork" button at the top right of this repository to create a copy in your GitHub account.

2. Clone Your Fork:

   • Clone the forked repository to your local machine using the following command:

     git clone https://github.com/your-username/stackblitz-webcontainer-api-starter.git

3. Navigate to the Project Directory:

   • Change into the project directory:

     cd stackblitz-webcontainer-api-starter

4. Install Dependencies:

   • Install the project dependencies:

     npm install

5. Run the Project:

   • Start the development server:

     npm run dev

6. Deploy to Cloudflare Workers (Optional):

   • Follow the instructions in the Adapting for Cloudflare Workers section to deploy your project as a serverless function on Cloudflare Workers.