@webcontainer/api
v1.5.1
Published
WebContainer Public API
Downloads
63,525
Readme
WebContainer Public API
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.
The WebContainer API relies on hosted proxies and server-side acceleration from StackBlitz to function properly. By integrating the WebContainer API into your project, you are agreeing to StackBlitz's standard Terms of Service.
How To
For an up-to-date documentation, please refer to our documentation.
Cross-Origin Isolation
WebContainer requires SharedArrayBuffer 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';
const files: FileSystemTree = {
'index.js': {
file: {
contents: '',
}
}
};
let webcontainer: WebContainer;
// add a textarea (the editor) and an iframe (a preview window) to the document
document.querySelector('#app').innerHTML = `
<div class="container">
<div class="editor">
<textarea>I am a textarea</textarea>
</div>
<div class="preview">
<iframe></iframe>
</div>
</div>
`;
// the editor
const textarea = document.querySelector('textarea');
// the preview window
const iframe = document.querySelector('iframe');
window.addEventListener('load', async () => {
textarea.value = files['index.js'].file.contents;
textarea.addEventListener('input', (event) => {
const content = event.currentTarget.value;
webcontainer.fs.writeFile('/index.js', content);
});
// call only once
webcontainer = await WebContainer.boot();
await webcontainer.mount(files);
const exitCode = await installDependencies();
if (exitCode !== 0) {
throw new Error('Installation failed');
}
startDevServer();
});
async function installDependencies() {
// install dependencies
const installProcess = await webcontainer.spawn('npm', ['install']);
installProcess.output.pipeTo(
new WritableStream({
write(data) {
console.log(data);
}
})
);
// wait for install command to exit
return installProcess.exit;
}
async function startDevServer() {
// run `npm run start` to start the express app
await webcontainer.spawn('npm', ['run', 'start']);
// wait for `server-ready` event
webcontainer.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.