WebContainer API

https://github.com/stackblitz/webcontainer-docs
Admin
WebContainer API provides a browser-based runtime for executing Node.js applications and operating...
Tokens:20,685
Snippets:303
Trust Score:9.5
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Run documentation site locally

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/README.md

Commands to install dependencies and start the development server after cloning the repository.

```sh
npm install
npm run dev
```

--------------------------------

### Install and Run Vite App

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/1-build-your-first-webcontainer-app.md

Navigates to the project directory, installs dependencies, and starts the development server.

```bash
cd webcontainers-express-app
npm install
npm run dev
```

--------------------------------

### Initialize application and start server

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/4-running-dev-server.md

Bootstraps the WebContainer instance, mounts files, installs dependencies, and triggers the dev server startup.

```js
window.addEventListener('load', async () => {
  textareaEl.value = files['index.js'].file.contents;
  // Call only once
  webcontainerInstance = await WebContainer.boot();
  await webcontainerInstance.mount(files);

  const exitCode = await installDependencies();
  if (exitCode !== 0) {
    throw new Error('Installation failed');
  };

  startDevServer();
});
```

--------------------------------

### Install dependencies

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/running-processes.md

Shows how to wait for an installation process to complete and retrieve its exit code.

```js
async function installDependencies() {
  // Install dependencies
  const installProcess = await webcontainerInstance.spawn('npm', ['install']);
  // Wait for install command to exit
  return installProcess.exit;
}
```

--------------------------------

### Start a development server

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/running-processes.md

Spawns a start command and listens for the server-ready event to handle incoming requests.

```js
async function startDevServer() {
  // Run `npm run start` to start the Express app
  await webcontainerInstance.spawn('npm', ['run', 'start']);

  // Wait for `server-ready` event
  webcontainerInstance.on('server-ready', (port, url) => {
    // ...
  });
}
```

--------------------------------

### Spawn Process Examples

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Demonstrates spawning processes with and without command-line arguments.

```js
const install = await webcontainerInstance.spawn('npm', ['i']);
```

```js
const install = await webcontainerInstance.spawn('yarn');
```

--------------------------------

### Start development server

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/4-running-dev-server.md

Spawns the npm start process and listens for the server-ready event to update the iframe source URL.

```js
async function startDevServer() {
  // Run `npm run start` to start the Express app
  await webcontainerInstance.spawn('npm', ['run', 'start']);

  // Wait for `server-ready` event
  webcontainerInstance.on('server-ready', (port, url) => {
    iframeEl.src = url;
  });
}
```

--------------------------------

### Initialize FileSystemTree Object

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Example structure showing nested directories, files, and symlinks.

```js
const tree = {
  myproject: {
    directory: {
      'foo.js': {
        file: {
          contents: 'const x = 1;',
        },
      },
      'bar.js': {
        file: {
          symlink: './foo.js',
        },
      },
      '.envrc': {
        file: {
          contents: 'ENVIRONMENT=staging'
        }
      },
    },
  },
  emptyFolder: {
    directory: {}
  },
};
```

--------------------------------

### Install @xterm/addon-fit

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/7-add-interactivity.md

Install the necessary dependency via npm.

```bash
npm install @xterm/addon-fit
```

--------------------------------

### Run commands and processes

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/quickstart.md

Execute shell commands like npm install or npm run dev using the spawn method.

```js
async function startDevServer() {
  const installProcess = await webcontainerInstance.spawn('npm', ['install']);

  const installExitCode = await installProcess.exit;

  if (installExitCode !== 0) {
    throw new Error('Unable to run npm install');
  }

  // `npm run dev`
  await webcontainerInstance.spawn('npm', ['run', 'dev']);
}
```

--------------------------------

### Install WebContainer API

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/quickstart.md

Install the package via npm within your project directory.

```bash
npm i @webcontainer/api
```

--------------------------------

### Watch Files and Directories for Changes

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Examples for watching a specific file and a directory recursively.

```js
webcontainerInstance.fs.watch('/src/main.js', (event) => {
    console.log(`action: ${event}`);
});
```

```js
webcontainerInstance.fs.watch('/src', { recursive: true }, (event, filename) => {
    console.log(`file: ${filename} action: ${event}`);
});
```

--------------------------------

### Spawn a process in WebContainer

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/3-installing-dependencies.md

Basic usage of the spawn method to execute npm install.

```javascript
webcontainerInstance.spawn('npm', ['install']);
```

--------------------------------

### Logged In Signature and Usage

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

The signature for the loggedIn function and an example of waiting for user authorization before installing private packages.

```typescript
loggedIn(): Promise<void>
```

```typescript
const instance = await WebContainer.boot();

// wait until the user is logged in
await auth.loggedIn();

// we can now fetch private packages from our organisation
await instance.spawn('npm', ['install']);
```

--------------------------------

### Start Auth Flow Signature

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

The signature for starting the OAuth flow.

```typescript
startAuthFlow(options?: { popup?: boolean }): void
```

--------------------------------

### Define Express Application Files

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/2-setting-up-webcontainers.md

Example content for the Express application files.

```js
import express from 'express';

const app = express();
const port = 3111;

app.get('/', (req, res) => {
  res.send('Welcome to a WebContainers app! 🥳');
});

app.listen(port, () => {
  console.log(`App is live at http://localhost:${port}`);
});
```

```json
{
  "name": "example-app",
  "type": "module",
  "dependencies": {
    "express": "latest",
    "nodemon": "latest"
  },
  "scripts": {
    "start": "nodemon --watch './' index.js"
  }
}
```

--------------------------------

### Call installDependencies with error handling

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/3-installing-dependencies.md

Integrates the installation function into the application lifecycle with basic error checking.

```javascript
window.addEventListener('load', async () => {
  textareaEl.value = files['index.js'].file.contents;
  // Call only once
  webcontainerInstance = await WebContainer.boot();
  await webcontainerInstance.mount(files);

  const exitCode = await installDependencies();
  if (exitCode !== 0) {
    throw new Error('Installation failed');
  };
});
```

--------------------------------

### Create loading.html

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/1-build-your-first-webcontainer-app.md

Defines the initial content displayed in the iframe while WebContainer dependencies are being installed.

```js
Installing dependencies...
```

--------------------------------

### auth.startAuthFlow

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Starts the OAuth flow to authenticate the user.

```APIDOC
## auth.startAuthFlow(options?: { popup?: boolean })

### Description
Starts the OAuth flow, redirecting the current page to the StackBlitz editor to authenticate the user. If popup is set to true, the flow occurs in a popup window.

### Parameters
- **options** (object) - Optional - Configuration object.
  - **popup** (boolean) - Optional - Whether to perform authentication in a popup.
```

--------------------------------

### Read a file

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Examples of reading file content with and without specified encoding.

```ts
const bytes = await webcontainerInstance.fs.readFile('/package.json');
```

```ts
const content = await webcontainerInstance.fs.readFile('/package.json', 'utf-8');
```

--------------------------------

### Install Xterm.js dependency

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/6-connect-a-terminal.md

Install the Xterm.js package via npm to enable terminal functionality in the browser.

```bash
npm install @xterm/xterm
```

--------------------------------

### Rename a file

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Example of renaming a file within the WebContainer file system.

```js
await webcontainerInstance.fs.rename('/src/index.js', '/src/main.js');
```

--------------------------------

### Initialize Vite Application

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/1-build-your-first-webcontainer-app.md

Creates a new project directory using the vanilla JavaScript template.

```bash
npm create vite webcontainers-express-app --template vanilla
```

--------------------------------

### Initialize WebContainer and mount files

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/2-setting-up-webcontainers.md

Boots the WebContainer instance and mounts the provided file system upon page load.

```js
window.addEventListener('load', async () => {
  textareaEl.value = files['index.js'].file.contents;
  
  // Call only once
  webcontainerInstance = await WebContainer.boot();
  await webcontainerInstance.mount(files);
});
```

--------------------------------

### Initialize and Load FitAddon

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/7-add-interactivity.md

Create a FitAddon instance, load it into the terminal, and call fit() after opening the terminal.

```js
window.addEventListener('load', async () => {
  textareaEl.value = files['index.js'].file.contents;
  textareaEl.addEventListener('input', (e) => {
    writeIndexJS(e.currentTarget.value);
  });

  const fitAddon = new FitAddon();

  const terminal = new Terminal({
    convertEol: true,
  });
  terminal.loadAddon(fitAddon);
  terminal.open(terminalEl);

  fitAddon.fit();

  // Call only once
  webcontainerInstance = await WebContainer.boot();
  await webcontainerInstance.mount(files);

  // Wait for `server-ready` event
  webcontainerInstance.on('server-ready', (port, url) => {
    iframeEl.src = url;
  });

  startShell(terminal);
});
```

--------------------------------

### Execute a basic command

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/running-processes.md

Demonstrates the basic syntax for spawning a process in a WebContainer instance.

```js
webcontainerInstance.spawn('npm', ['install']);
```

```js
webcontainerInstance.spawn('ls', ['src', '-l']);
```

--------------------------------

### Initialize and mount files in WebContainer

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/2-setting-up-webcontainers.md

Boot the WebContainer instance and mount the file system object during the window load event.

```js
import './style.css';
import { WebContainer } from '@webcontainer/api';
import { files } from './files';

/** @type {import('@webcontainer/api').WebContainer}  */
let webcontainerInstance;

window.addEventListener('load', async () => {
  // Call only once
  webcontainerInstance = await WebContainer.boot();
  await webcontainerInstance.mount(files);
});
```

--------------------------------

### Create a WebContainer instance

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/quickstart.md

Initialize the WebContainer instance using the boot method. This method must be called only once per application lifecycle.

```js
import { WebContainer } from '@webcontainer/api';

// Call only once
const webcontainerInstance = await WebContainer.boot();
```

--------------------------------

### Initialize the terminal and shell

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/7-add-interactivity.md

Integrates the shell startup into the window load event listener after booting the WebContainer instance.

```js
window.addEventListener('load', async () => {
  textareaEl.value = files['index.js'].file.contents;
  textareaEl.addEventListener('input', (e) => {
    writeIndexJS(e.currentTarget.value);
  });

  const terminal = new Terminal({
    convertEol: true,
  });
  terminal.open(terminalEl);

  // Call only once
  webcontainerInstance = await WebContainer.boot();
  await webcontainerInstance.mount(files);

  // Wait for `server-ready` event
  webcontainerInstance.on('server-ready', (port, url) => {
    iframeEl.src = url;
  });

  startShell(terminal);
});
```

--------------------------------

### WebContainer.boot

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Boots a WebContainer instance. Only one instance can be booted concurrently.

```APIDOC
## static boot(options: BootOptions = {}): Promise<WebContainer>

### Description
Boots a WebContainer. Only a single instance of WebContainer can be booted concurrently. Booting is an expensive operation.

### Parameters
- **options** (BootOptions) - Optional - Configuration options for the boot process.

### BootOptions
- **coep** ('require-corp' | 'credentialless' | 'none') - Optional - The value of the COEP header used to load the application.
- **workdirName** (string) - Optional - Sets the folder name for the working directory.
- **forwardPreviewErrors** (boolean | 'exceptions-only') - Optional - Configure whether errors occurring in embedded preview iframes should be forwarded to the parent page.
```

--------------------------------

### Initialize Terminal and Pass to Methods

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/6-connect-a-terminal.md

Create a Terminal instance and pass it as an argument to your process-handling functions.

```js
window.addEventListener('load', async () => {
  textareaEl.value = files['index.js'].file.contents;
  textareaEl.addEventListener('input', (e) => {
    writeIndexJS(e.currentTarget.value);
  });

  const terminal = new Terminal({
    convertEol: true,
  });
  terminal.open(terminalEl);

  // Call only once
  webcontainerInstance = await WebContainer.boot();
  await webcontainerInstance.mount(files);

  const exitCode = await installDependencies(terminal);
  if (exitCode !== 0) {
    throw new Error('Installation failed');
  };

  startDevServer(terminal);
});
```

--------------------------------

### Define BootOptions interface

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Configuration options for booting a WebContainer instance.

```ts
interface BootOptions {
  coep?: 'require-corp' | 'credentialless' | 'none';
  workdirName?: string;
  forwardPreviewErrors?: boolean | 'exceptions-only';
}
```

--------------------------------

### Preview the application

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/quickstart.md

Listen for the server-ready event to retrieve the application URL and display it in an iframe.

```js
webcontainerInstance.on('server-ready', (port, url) => (iframeEl.src = url));
```

--------------------------------

### spawn(command, args, options)

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Spawns a new process within the WebContainer environment.

```APIDOC
## spawn(command, args, options)

### Description
Spawns a process inside the WebContainer. Supports optional command-line arguments and configuration options.

### Signature
`spawn(command: string, args?: string[], options?: SpawnOptions): Promise<WebContainerProcess>`

### Parameters
- **command** (string) - The command to execute.
- **args** (string[]) - Optional array of command-line arguments.
- **options** (SpawnOptions) - Optional configuration for the spawned process.

### Returns
- **Promise<WebContainerProcess>** - A promise that resolves to the spawned process instance.
```

--------------------------------

### Define mkdir options

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Interface for configuring directory creation behavior.

```ts
interface Options {
  recursive?: boolean;
}
```

--------------------------------

### Initialize and render the terminal

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/6-connect-a-terminal.md

Create a new Terminal instance and attach it to the referenced DOM element within the window load event.

```js
window.addEventListener('load', async () => {
  textareaEl.value = files['index.js'].file.contents;
  textareaEl.addEventListener('input', (e) => {
    writeIndexJS(e.currentTarget.value);
  });

  const terminal = new Terminal({
    convertEol: true,
  });
  terminal.open(terminalEl);

  // Call only once
  webcontainerInstance = await WebContainer.boot();
  await webcontainerInstance.mount(files);

  const exitCode = await installDependencies();
  if (exitCode !== 0) {
    throw new Error('Installation failed');
  };

  startDevServer();
});
```

--------------------------------

### Create a Directory Before Mounting

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/working-with-the-file-system.md

Ensure the target directory exists using the mkdir method before mounting files to avoid errors.

```js
await webcontainerInstance.fs.mkdir('my-mount-point');
await webcontainerInstance.mount(files, { mountPoint: 'my-mount-point' });
```

--------------------------------

### Initialize App HTML in main.js

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/1-build-your-first-webcontainer-app.md

Injects the container, textarea, and iframe elements into the #app DOM node.

```js
document.querySelector('#app').innerHTML = `
  <div class="container">
    <div class="editor">
      <textarea>I am a textarea</textarea>
    </div>
    <div class="preview">
      <iframe src="loading.html"></iframe>
    </div>
  </div>
`
```

--------------------------------

### Translate shell commands to spawn syntax

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/3-installing-dependencies.md

Demonstrates how to convert standard shell commands into the array-based argument format required by the spawn method.

```bash
cd hello-world
```

```javascript
webcontainerInstance.spawn('cd', ['hello-world']);
```

```bash
ls src -l
```

```javascript
webcontainerInstance.spawn('ls', ['src', '-l']);
```

--------------------------------

### Import FitAddon

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/7-add-interactivity.md

Import the FitAddon class into the main JavaScript file.

```js
import { FitAddon } from '@xterm/addon-fit';
```

--------------------------------

### Create Directories

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/working-with-the-file-system.md

Create new directories, supporting nested paths via the recursive option.

```javascript
await webcontainerInstance.fs.mkdir('src');
```

```javascript
await webcontainerInstance.fs.mkdir('this/is/my/nested/folder', { recursive: true });
```

--------------------------------

### Import Files into Main

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/2-setting-up-webcontainers.md

Import the defined file system object into the main application file.

```js
import { files } from './files';
```

--------------------------------

### mkdir

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Creates a new directory. Throws an error if the directory already exists.

```APIDOC
## mkdir(path: string, options?: Options): Promise<void>

### Description
Creates a new directory at the specified path. If the directory already exists, it will throw an error.

### Parameters
- **path** (string) - Required - The path of the directory to create.
- **options** (Options) - Optional - Configuration options.
  - **recursive** (boolean) - Optional - When set to true, it will create any missing folders in the path.
```

--------------------------------

### webcontainerInstance.fs.mkdir

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/working-with-the-file-system.md

Creates a new directory at the specified path.

```APIDOC
## webcontainerInstance.fs.mkdir(path, [options])

### Description
Creates a directory at the given path. If the directory already exists, it will throw an error. Use `recursive: true` to create nested folders.
```

--------------------------------

### Mount a Snapshot in WebContainer

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/working-with-the-file-system.md

Fetch a binary snapshot from a server and mount it into the WebContainer instance.

```typescript
import { WebContainer } from '@webcontainer/api';

const webcontainer = await WebContainer.boot();

const snapshotResponse = await fetch('/snapshot');
const snapshot = await snapshotResponse.arrayBuffer();

await webcontainer.mount(snapshot);
```

--------------------------------

### Create File System Tree

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/2-setting-up-webcontainers.md

Define the file structure object to be mounted into the WebContainer.

```js
/** @satisfies {import('@webcontainer/api').FileSystemTree} */

export const files = {
  'index.js': {
    file: {
      contents: `
import express from 'express';
const app = express();
const port = 3111;

app.get('/', (req, res) => {
  res.send('Welcome to a WebContainers app! 🥳');
});

app.listen(port, () => {
  console.log(\`App is live at http://localhost:\${port}\`);
});`,
    },
  },
  'package.json': {
    file: {
      contents: `
{
  "name": "example-app",
  "type": "module",
  "dependencies": {
    "express": "latest",
    "nodemon": "latest"
  },
  "scripts": {
    "start": "nodemon --watch './' index.js"
  }
}`,
    },
  },
};
```

--------------------------------

### Define mount Options interface

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Configuration options for mounting files into the filesystem.

```ts
interface Options {
  mountPoint?: string;
}
```

--------------------------------

### auth.init

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Initializes authentication for use in WebContainer.

```APIDOC
## auth.init(options: AuthInitOptions)

### Description
Initializes the authentication for use in WebContainer. This method should be called as soon as possible during the page loading phase.

### Parameters
- **options** (AuthInitOptions) - Required - Configuration object containing clientId, scope, and optional editorOrigin.

### Returns
- **{ status: 'need-auth' | 'authorized' } | AuthFailedError** - Returns the authentication status or an error object.

### Notes
This function will throw an exception if WebContainer.boot was called before auth.init.
```

--------------------------------

### Configure SvelteKit Headers

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/configuring-headers.md

Use hooks.server.js for global or conditional logic, or +page.server.js for route-specific header injection.

```js
export const handle = async ({ request, resolve }) => {
  const response = await resolve(request);

  response.headers.set('Cross-Origin-Embedder-Policy', 'require-corp');
  response.headers.set('Cross-Origin-Opener-Policy', 'same-origin');

  return response;
};
```

```js
export const handle = async ({ request, resolve }) => {
  const response = await resolve(request);

  if (request.path === '/tutorial') {
    response.headers.set('Cross-Origin-Embedder-Policy', 'require-corp');
    response.headers.set('Cross-Origin-Opener-Policy', 'same-origin');
  }

  return response;
};
```

```js
/** @type {import('./$types').PageServerLoad} */
export const load = ({ setHeaders }) => {
  setHeaders({
    'Cross-Origin-Embedder-Policy': 'require-corp',
    'Cross-Origin-Opener-Policy': 'same-origin',
  });
};
```

--------------------------------

### Update main.js for interactive terminal

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/7-add-interactivity.md

Configures the terminal listener to wait for the server-ready event after booting the WebContainer instance.

```js
window.addEventListener('load', async () => {
  textareaEl.value = files['index.js'].file.contents;
  textareaEl.addEventListener('input', (e) => {
    writeIndexJS(e.currentTarget.value);
  });

  const terminal = new Terminal({
    convertEol: true,
  });
  terminal.open(terminalEl);

  // Call only once
  webcontainerInstance = await WebContainer.boot();
  await webcontainerInstance.mount(files);

  // Wait for `server-ready` event
  webcontainerInstance.on('server-ready', (port, url) => {
    iframeEl.src = url;
  });
});
```

--------------------------------

### AuthInitOptions Interface

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Configuration options for initializing authentication.

```typescript
interface AuthInitOptions {
  /**
   * StackBlitz' origin.
   *
   * @default https://stackblitz.com
   */
  editorOrigin?: string;

  /**
   * The client id for this OAuth application.
   */
  clientId: string;

  /**
   * OAuth scope. The value can be found under your `Teams Settings` > `API`.
   *
   * @see https://www.rfc-editor.org/rfc/rfc6749#section-3.3
   */
  scope: string;
}
```

--------------------------------

### Configure Netlify Headers

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/configuring-headers.md

Define headers in netlify.toml for global or route-specific application.

```toml
[[headers]]
  for = "/*"
  [headers.values]
    Cross-Origin-Embedder-Policy = "require-corp"
    Cross-Origin-Opener-Policy = "same-origin"
```

```toml
[[headers]]
  for = "/tutorial"
  [headers.values]
    Cross-Origin-Embedder-Policy = "require-corp"
    Cross-Origin-Opener-Policy = "same-origin"
```

--------------------------------

### Generate and Serve Snapshots

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/working-with-the-file-system.md

Use the @webcontainer/snapshot package to create binary snapshots of folders for server-side delivery.

```typescript
import { snapshot } from '@webcontainer/snapshot';

// snapshot is a `Buffer`
const folderSnapshot = await snapshot(SOURCE_CODE_FOLDER);

// for an express-based application
app.get('/snapshot', (req, res) => {
  res
    .setHeader('content-type', 'application/octet-stream')
    .send(snapshot);
});

// for a SvelteKit-like application
export function getSnapshot(req: Request) {
  return new Response(sourceSnapshot, {
    headers: {
      'content-type': 'application/octet-stream',
    },
  });
}
```

--------------------------------

### Mount files into the file system

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/quickstart.md

Use the mount method to hydrate the WebContainer file system with your project files.

```js
await webcontainerInstance.mount(projectFiles);
```

--------------------------------

### Execute commands in a specific directory

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/troubleshooting.md

Use the --cwd flag within the spawn method to target a specific project directory.

```js
webcontainer.spawn('turbo', ['--cwd', `~/projects/${id}`, 'exec', 'astro', 'dev']);
```

--------------------------------

### Mount multiple files in WebContainer

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/working-with-the-file-system.md

Expands the FileSystemTree object to include multiple files by adding additional keys.

```js
/** @type {import('@webcontainer/api').FileSystemTree} */

const files = {
  'package.json': {
    file: {
      contents: `
        {
          "name": "vite-starter",
          "private": true,
          "version": "0.0.0",
          "type": "module",
          "scripts": {
            "dev": "vite",
            "build": "vite build",
            "preview": "vite preview"
          },
          "devDependencies": {
            "vite": "^4.0.4"
          }
        }`,
    },
  },
  'index.html': {
    file: {
      contents: `
        <!DOCTYPE html>
        <html lang="en">
          <head>
            <meta charset="UTF-8" />
            <link rel="icon" type="image/svg+xml" href="/vite.svg" />
            <meta name="viewport" content="width=device-width, initial-scale=1.0" />
            <title>Vite App</title>
          </head>
          <body>
            <div id="app"></div>
            <script type="module" src="/src/main.js"></script>
          </body>
        </html>`,
    },
  },
};

await webcontainerInstance.mount(files);
```

--------------------------------

### Mount a single file in WebContainer

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/working-with-the-file-system.md

Uses the FileSystemTree structure to mount a package.json file at the root of the file system.

```js
/** @type {import('@webcontainer/api').FileSystemTree} */

const files = {
  'package.json': {
    file: {
      contents: `
        {
          "name": "vite-starter",
          "private": true,
          "version": "0.0.0",
          "type": "module",
          "scripts": {
            "dev": "vite",
            "build": "vite build",
            "preview": "vite preview"
          },
          "devDependencies": {
            "vite": "^4.0.4"
          }
        }`,
    },
  },
};

await webcontainerInstance.mount(files);
```

--------------------------------

### WebContainer.mount

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Mounts a tree of files into the filesystem.

```APIDOC
## mount(tree: FileSystemTree | Uint8Array | ArrayBuffer, options?: Options): Promise<void>

### Description
Mounts a tree of files into the filesystem. This can be specified as a FileSystemTree object or as a binary snapshot.

### Parameters
- **tree** (FileSystemTree | Uint8Array | ArrayBuffer) - Required - The file tree or binary snapshot to mount.
- **options** (Options) - Optional - Configuration options for the mount operation.

### Options
- **mountPoint** (string) - Optional - The path where the files should be mounted.
```

--------------------------------

### Implement responsive terminal resizing

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/7-add-interactivity.md

Use the resize event listener to update the shell process dimensions whenever the browser window is resized.

```js
window.addEventListener('load', async () => {
  textareaEl.value = files['index.js'].file.contents;
  textareaEl.addEventListener('input', (e) => {
    writeIndexJS(e.currentTarget.value);
  });

  const fitAddon = new FitAddon();

  const terminal = new Terminal({
    convertEol: true,
  });
  terminal.loadAddon(fitAddon);
  terminal.open(terminalEl);

  fitAddon.fit();

  // Call only once
  webcontainerInstance = await WebContainer.boot();
  await webcontainerInstance.mount(files);

  // Wait for `server-ready` event
  webcontainerInstance.on('server-ready', (port, url) => {
    iframeEl.src = url;
  });

  const shellProcess = await startShell(terminal);
  window.addEventListener('resize', () => {
    fitAddon.fit();
    shellProcess.resize({
      cols: terminal.cols,
      rows: terminal.rows,
    });
  });
});
```

--------------------------------

### Import Xterm.js

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/6-connect-a-terminal.md

Add the Xterm.js library import to the top of the main script file.

```js
import { Terminal } from '@xterm/xterm'
```

--------------------------------

### export(path: string, options?: ExportOptions)

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Exports the filesystem at the specified path. Returns a FileSystemTree if the format is json, or a Uint8Array otherwise.

```APIDOC
## export(path: string, options?: ExportOptions)

### Description
Exports the filesystem at the specified path. Returns a FileSystemTree if the format is json, or a Uint8Array otherwise.

### Signature
`export(path: string, options?: ExportOptions): Promise<Uint8Array | FileSystemTree>`

### Example
```js
const data = await webcontainerInstance.export('dist', { format: 'zip' });
const zip = new Blob([data]);
```
```

--------------------------------

### Mount Files to a Custom Path

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/working-with-the-file-system.md

Mount a file system tree to a specific directory using the mountPoint property.

```js
/** @type {import('@webcontainer/api').FileSystemTree} */

const files = {
  'package.json': {
    /* Omitted for brevity */
  },
  'index.html': {
    /* Omitted for brevity */
  },
};

await webcontainerInstance.mount(files, { mountPoint: 'my-mount-point' });
```

--------------------------------

### on

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Registers event listeners for authentication-related events.

```APIDOC
## on(event: 'logged-out' | 'auth-failed', listener: ...): () => void

### Description
Listens for specific authentication events. Returns a function to unsubscribe from the events.

### Overloads
- **on(event: 'logged-out', listener: () => void)**: Emitted when credentials are revoked.
- **on(event: 'auth-failed', listener: (reason: { error: string, description: string }) => void)**: Emitted when the user declines authorization. 
  - `error`: The error code (e.g., 'access_denied', 'invalid_scope').
  - `description`: Human-readable error description.
```

--------------------------------

### Configure Vercel Headers

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/configuring-headers.md

Use vercel.json to apply headers globally or to specific paths.

```json
{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "Cross-Origin-Embedder-Policy",
          "value": "require-corp"
        },
        {
          "key": "Cross-Origin-Opener-Policy",
          "value": "same-origin"
        }
      ]
    }
  ]
}
```

```json
{
  "headers": [
    {
      "source": "/tutorial",
      "headers": [
        {
          "key": "Cross-Origin-Embedder-Policy",
          "value": "require-corp"
        },
        {
          "key": "Cross-Origin-Opener-Policy",
          "value": "same-origin"
        }
      ]
    }
  ]
}
```

--------------------------------

### webcontainerInstance.fs.writeFile

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/working-with-the-file-system.md

Writes data to a file, creating it if it doesn't exist or overwriting it if it does.

```APIDOC
## webcontainerInstance.fs.writeFile(path, data, [options])

### Description
Writes a file to the given path. If the file does not exist, it will create a new one. If the file exists, it will overwrite the file.
```

--------------------------------

### Define readdir options

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Interface for configuring directory reading behavior.

```ts
interface Options {
  encoding?: BufferEncoding;
  withFileTypes?: boolean;
}
```

--------------------------------

### Auth Init Signature

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

The signature for the auth.init function. This function will throw an exception if WebContainer.boot was called before it.

```typescript
init(options: AuthInitOptions): { status: 'need-auth' | 'authorized' } | AuthFailedError
```

--------------------------------

### Pipe Process Output to Terminal

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/6-connect-a-terminal.md

Use a WritableStream to pipe the output of spawned processes into the terminal instance.

```js
/**
 * @param {Terminal} terminal
 */
async function installDependencies(terminal) {
  // Install dependencies
  const installProcess = await webcontainerInstance.spawn('npm', ['install']);
  installProcess.output.pipeTo(new WritableStream({
    write(data) {
      terminal.write(data);
    }
  }))
  // Wait for install command to exit
  return installProcess.exit;
}
```

```js
/**
 * @param {Terminal} terminal
 */
async function startDevServer(terminal) {
  // Run `npm run start` to start the Express app
  const serverProcess = await webcontainerInstance.spawn('npm', [
    'run',
    'start',
  ]);
  serverProcess.output.pipeTo(
    new WritableStream({
      write(data) {
        terminal.write(data);
      },
    })
  );

  // Wait for `server-ready` event
  webcontainerInstance.on('server-ready', (port, url) => {
    iframeEl.src = url;
  });
}
```

--------------------------------

### Define a directory in the virtual file system

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/working-with-the-file-system.md

Directories are represented as objects with a 'directory' key.

```javascript
const files = {
  // This is a directory - provide its name as a key
  src: {
    // Because it's a directory, add the "directory" key
    directory: {
      // Here we will add files
    },
  },
};
```

--------------------------------

### Configure Cloudflare Headers

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/configuring-headers.md

Set headers for all pages or specific routes using the _headers file.

```yaml
/*
  Cross-Origin-Embedder-Policy: require-corp
  Cross-Origin-Opener-Policy: same-origin
```

```yaml
/tutorial
  Cross-Origin-Embedder-Policy: require-corp
  Cross-Origin-Opener-Policy: same-origin
```

--------------------------------

### Define SpawnOptions interface

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Configuration options for controlling process spawning behavior, including working directory and environment variables.

```ts
export interface SpawnOptions {
  cwd?: string;
  env?: Record<string, string | number | boolean>;
  output?: boolean;
  terminal?: { cols: number; rows: number };
}
```

--------------------------------

### Import Xterm.js CSS

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/6-connect-a-terminal.md

Import the required CSS styles at the top of your main.js file to ensure the terminal renders correctly.

```js
import '@xterm/xterm/css/xterm.css';
```

--------------------------------

### writeFile(path: string, data: string | Uint8Array, options?: object): Promise<void>

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Writes a file to the given path, creating it if it does not exist or overwriting it if it does.

```APIDOC
## writeFile(path: string, data: string | Uint8Array, options?: object): Promise<void>

### Description
Writes a file to the given path. If the file does not exist, it will create a new one. If the file exists, it will overwrite the file.

### Parameters
- **path** (string) - Required - The path to the file.
- **data** (string | Uint8Array) - Required - The content to write.
- **options** (object) - Optional - Encoding options.
  - **encoding** (string | null) - Optional - The character encoding to use.

### Example
```js
await webcontainerInstance.fs.writeFile('/src/main.js', 'console.log("Hello from WebContainers!")');
```
```

--------------------------------

### Write Files with WebContainer fs

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/working-with-the-file-system.md

Create or overwrite files, optionally specifying an encoding.

```javascript
await webcontainerInstance.fs.writeFile('/src/main.js', 'console.log("Hello from WebContainers!")');
```

```javascript
await webcontainerInstance.fs.writeFile(
  '/src/main.js',
  '\xE5\x8D\x83\xE8\x91\x89\xE5\xB8\x82\xE3\x83\x96\xE3\x83\xAB\xE3\x83\xBC\xE3\x82\xB9',
  { encoding: 'latin1' }
);
```

--------------------------------

### Configure Next.js Headers

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/configuring-headers.md

Implement the async headers function in next.config.js to return header objects for specific source paths.

```js
// https://nextjs.org/docs/api-reference/next.config.js/introduction
module.exports = {
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          {
            key: 'Cross-Origin-Embedder-Policy',
            value: 'require-corp',
          },
          {
            key: 'Cross-Origin-Opener-Policy',
            value: 'same-origin',
          },
        ],
      },
    ];
  },
};
```

```js
// https://nextjs.org/docs/api-reference/next.config.js/introduction
module.exports = {
  async headers() {
    return [
      {
        source: '/tutorial',
        headers: [
          {
            key: 'Cross-Origin-Embedder-Policy',
            value: 'require-corp',
          },
          {
            key: 'Cross-Origin-Opener-Policy',
            value: 'same-origin',
          },
        ],
      },
    ];
  },
};
```

--------------------------------

### Configure API Key Signature

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

The signature for the configureAPIKey function. This function will throw an exception if WebContainer.boot was called before it.

```typescript
configureAPIKey(key: string): void
```

--------------------------------

### Apply CSS Styles

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/1-build-your-first-webcontainer-app.md

Configures the layout using CSS grid and styles the textarea and iframe components.

```css
* {
  box-sizing: border-box;
}

body {
  margin: 0;
  height: 100vh;
}

.container {
  display: grid;
  grid-template-columns: 1fr 1fr;
  gap: 1rem;
  height: 100%;
  width: 100%;
}

textarea {
  width: 100%;
  height: 100%;
  resize: none;
  border-radius: 0.5rem;
  background: black;
  color: white;
  padding: 0.5rem 1rem;
}

iframe {
  height: 100%;
  width: 100%;
  border-radius: 0.5rem;
}
```

--------------------------------

### Update main.js

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/1-build-your-first-webcontainer-app.md

Clears the default content in the main entry file to prepare for custom WebContainer implementation.

```js
import './style.css';

document.querySelector('#app').innerHTML = ``;
```

--------------------------------

### Read file contents from WebContainer

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/2-setting-up-webcontainers.md

Use the fs.readFile method on the booted instance to access and log file contents.

```js
window.addEventListener('load', async () => {
  // Call only once
  webcontainerInstance = await WebContainer.boot();
  await webcontainerInstance.mount(files);

  const packageJSON = await webcontainerInstance.fs.readFile('package.json', 'utf-8');
  console.log(packageJSON);
});
```

--------------------------------

### configureAPIKey

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Configures an API key for commercial usage of the WebContainer API.

```APIDOC
## configureAPIKey(key: string)

### Description
Configure an API key to be used for commercial usage of the WebContainer API.

### Parameters
- **key** (string) - Required - The API key string.

### Notes
This function will throw an exception if WebContainer.boot was called before configureAPIKey.
```

--------------------------------

### Define FileSystemTree Interface

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

The base interface for describing a folder structure.

```ts
interface FileSystemTree {
  [name: string]: FileNode | SymlinkNode | DirectoryNode;
}
```

--------------------------------

### ServerReadyListener Type Definition

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Defines the signature for the server-ready event listener.

```ts
(port: number, url: string): void
```

--------------------------------

### webcontainerInstance.fs.readdir

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/working-with-the-file-system.md

Reads a directory and returns an array of its contents.

```APIDOC
## webcontainerInstance.fs.readdir(path, [options])

### Description
Reads a given directory and returns an array of its files and directories. Throws an error if the directory does not exist.

### Parameters
- **path** (string) - Required - The path to the directory.
- **options** (object) - Optional - Configuration object containing `withFileTypes` (boolean) or `encoding` (string).
```

--------------------------------

### watch(path: string, options?: Options, listener: Listener): Watcher

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Watch for changes to a given file or directory.

```APIDOC
## watch(path: string, options?: Options, listener: Listener): Watcher

### Description
Watch for changes to a given file or directory. Returns a Watcher object with a close() method.

### Parameters
- **path** (string) - Required - The path to watch.
- **options** (Options) - Optional - Configuration object.
  - **encoding** (string) - Optional - Character encoding for the filename. Default: 'utf8'.
  - **recursive** (boolean) - Optional - Whether to watch subdirectories. Default: false.
- **listener** (function) - Required - Callback function (event: 'rename' | 'change', filename: string | Buffer) => void.

### Example
```js
webcontainerInstance.fs.watch('/src/main.js', (event) => {
    console.log(`action: ${event}`);
});
```
```

--------------------------------

### Add URL patterns for StackBlitz domain exceptions

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/browser-config.md

Use these patterns in your browser's cookie or site settings to allow Service Workers and third-party storage for WebContainers.

```text
https://[*.]stackblitz.io
https://[*.]webcontainer.io
```

--------------------------------

### Read Directories with WebContainer fs

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/working-with-the-file-system.md

List directory contents, optionally returning Dirent objects or buffers.

```javascript
const files = await webcontainerInstance.fs.readdir('/src');
//    ^ is an array of strings
```

```javascript
const files = await webcontainerInstance.fs.readdir('/src', {
  withFileTypes: true,
});
```

```javascript
const files = await webcontainerInstance.fs.readdir('/src', { encoding: 'buffer' });
//    ^ it is an array of UInt8Array
```

--------------------------------

### Credentialless COOP/COEP Header Configuration

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/configuring-headers.md

Alternative headers for browsers supporting the credentialless mode.

```yaml
Cross-Origin-Embedder-Policy: credentialless
Cross-Origin-Opener-Policy: same-origin
```

--------------------------------

### Spawn a shell process

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/7-add-interactivity.md

Creates a function to spawn the 'jsh' shell and pipe its output stream to an Xterm.js terminal instance.

```js
/**
 * @param {Terminal} terminal
 */
async function startShell(terminal) {
  const shellProcess = await webcontainerInstance.spawn('jsh');
  shellProcess.output.pipeTo(
    new WritableStream({
      write(data) {
        terminal.write(data);
      },
    })
  );
  return shellProcess;
};
```

--------------------------------

### Define a file in the virtual file system

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/working-with-the-file-system.md

Files are represented as objects with a 'file' key containing the 'contents' property.

```javascript
const files = {
  // This is a file - provide its path as a key:
  'package.json': {
    // Because it's a file, add the "file" key
    file: {
      // Now add its contents
      contents: `
        {
          "name": "vite-starter",
          "private": true,
         // ...
          },
          "devDependencies": {
            "vite": "^4.0.4"
          }
        }`,
    },
  },
};
```

--------------------------------

### Define Options Interface for watch

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Configuration interface for the watch method.

```ts
interface Options {
  encoding?: BufferEncoding | null;
  recursive?: boolean;
}
```

--------------------------------

### Read a file from the file system

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/working-with-the-file-system.md

Accesses the contents of a previously mounted file using the fs.readFile method.

```js
const file = await webcontainerInstance.fs.readFile('/package.json');
```

--------------------------------

### rm(path: string, options?: Options): Promise<void>

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Deletes a file or a directory. If the path is a directory, the recursive option must be set to true.

```APIDOC
## rm(path: string, options?: Options): Promise<void>

### Description
Deletes a file or a directory. If the path is a file, it will delete the file. If the path is a directory, a second argument is needed with option `recursive` set to `true` to delete the directory and everything inside it.

### Parameters
- **path** (string) - Required - The path to the file or directory to delete.
- **options** (Options) - Optional - Configuration object.
  - **force** (boolean) - Optional - When true, exceptions are ignored if the path does not exist.
  - **recursive** (boolean) - Optional - If true, recursively removes directories.

### Example
```js
await webcontainerInstance.fs.rm('/src/main.js');
await webcontainerInstance.fs.rm('/src', { recursive: true });
```
```

--------------------------------

### Define PreviewScriptOptions interface

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Interface defining attributes for scripts injected into previews.

```ts
export interface PreviewScriptOptions {
  type?: 'module' | 'importmap';
  defer?: boolean;
  async?: boolean;
}
```

--------------------------------

### Reference the terminal element

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/6-connect-a-terminal.md

Select the terminal container element from the DOM to serve as the mounting point.

```js
/** @type {HTMLTextAreaElement | null} */
const terminalEl = document.querySelector('.terminal');
```

--------------------------------

### auth.loggedIn

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Returns a promise that resolves when the user has authorized the application.

```APIDOC
## auth.loggedIn()

### Description
Returns a promise that resolves when the user authorized your application. This promise is guaranteed to never be rejected. If the user never authorizes or declines, the promise never resolves.

### Returns
- **Promise<void>** - Resolves upon successful authorization.
```

--------------------------------

### Configure COOP/COEP headers in Vite

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/2-setting-up-webcontainers.md

Required security headers for WebContainers to run. Add these to the vite.config.js file to enable the necessary cross-origin policies.

```yaml
Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin
```

```js
import { defineConfig } from 'vite';

export default defineConfig({
  server: {
    headers: {
      'Cross-Origin-Embedder-Policy': 'require-corp',
      'Cross-Origin-Opener-Policy': 'same-origin',
    },
  },
});
```

--------------------------------

### Define a File System Tree

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/working-with-the-file-system.md

Structure a file system hierarchy using the FileSystemTree API, specifying directories and files with their contents.

```yaml
- src
  - main.js
  - main.css
- index.html
- package.json
```

```js
/** @type {import('@webcontainer/api').FileSystemTree} */

const files = {
  // This is a directory - provide its name as a key
  src: {
    // Because it's a directory, add the "directory" key
    directory: {
      // This is a file - provide its path as a key:
      'main.js': {
        // Because it's a file, add the "file" key
        file: {
          contents: `
            console.log('Hello from WebContainers!')
          `,
        },
      },
      // This is another file inside the same folder
      'main.css': {
        // Because it's a file, add the "file" key
        file: {
          contents: `
            body {
              margin: 0;
            }
          `,
        },
      },
    },
  },
  // This is a file outside the folder
  'package.json': {
    /* Omitted for brevity */
  },
  // This is another file outside the folder
  'index.html': {
    /* Omitted for brevity */
  },
};

await webcontainerInstance.mount(files);
```

--------------------------------

### Listen for preview-message events

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/api.md

Register an event handler to receive errors or messages forwarded from embedded preview iframes.

```js
webcontainerInstance.on('preview-message', (message) => {
  // process the message received from a preview
});
```

--------------------------------

### Stream process output

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/3-installing-dependencies.md

Captures and logs the output of a spawned process using a WritableStream.

```javascript
  const installProcess = await webcontainerInstance.spawn('npm', ['install']);
  
  installProcess.output.pipeTo(new WritableStream({
    write(data) {
      console.log(data);
    }
  }));
```

--------------------------------

### Update loading.html message

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/7-add-interactivity.md

Updates the UI prompt to instruct the user to interact with the terminal.

```html
Use the terminal to run a command!
```

--------------------------------

### Create a function to write a file

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/tutorial/5-editing-a-file-updating-the-iframe.md

Uses the fs.writeFile method to update the contents of index.js within the WebContainer file system.

```js
/** @param {string} content*/

async function writeIndexJS(content) {
  await webcontainerInstance.fs.writeFile('/index.js', content);
};
```

--------------------------------

### Add Edge Security Exceptions

Source: https://github.com/stackblitz/webcontainer-docs/blob/main/docs/guides/browser-config.md

Add these domains to the Microsoft Edge 'Enhanced security' exceptions list to allow WebAssembly execution.

```text
stackblitz.com
[*.]staticblitz.com
```
Tokens:
Raw