WebContainer API

https://webcontainers.io
Admin
WebContainer API is a browser-based runtime that enables you to run Node.js applications and execute...
Tokens:39,037
Snippets:430
Trust Score:8.6
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install dependencies and run the dev server

Source: https://webcontainers.io/tutorial/1-build-your-first-webcontainer-app

After creating the Vite app, enter the project directory, install dependencies, and start the dev server. The terminal will display a localhost URL to preview the page.

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

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

### Start dev server and listen for server-ready event

Source: https://webcontainers.io/tutorial/4-running-dev-server

Defines the startDevServer function that runs `npm run start` via webcontainerInstance.spawn and listens for the 'server-ready' event to set the iframe's src to the server URL. Add this to main.js after mounting files and installing dependencies.

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

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

### Start a dev server and listen for server-ready

Source: https://webcontainers.io/guides/running-processes

Runs `npm run start` to start a dev server and listens for the `server-ready` event. The event provides the port and URL of the server.

```javascript
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) => {
    // ...
  });
}
```

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

### Create loading.html with placeholder text

Source: https://webcontainers.io/tutorial/1-build-your-first-webcontainer-app

Creates a loading.html file that will be shown in the iframe while the WebContainer is getting ready. It displays 'Installing dependencies...'.

```html
Installing dependencies...
```

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

### Start shell in load event listener

Source: https://webcontainers.io/tutorial/7-add-interactivity

Event listener that initializes the WebContainer, mounts files, sets up the terminal, and starts the shell by calling startShell(terminal) at the end. This is the main setup for the interactive terminal example.

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

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

### Run npm install and dev server

Source: https://webcontainers.io/guides/quickstart

Spawns npm install and npm run dev. Throws an error if npm install exits with non-zero code.

```javascript
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']);
}
```

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

### Pipe npm run start output to terminal and handle server-ready

Source: https://webcontainers.io/tutorial/6-connect-a-terminal

Starts the dev server with npm run start and pipes its output to the terminal. Listens for the 'server-ready' event to set the iframe source to the server URL.

```javascript
/**
 * @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;
  });
}
```

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

### spawn with args example

Source: https://webcontainers.io/api

Spawns a process with command-line arguments, here running 'npm i'.

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

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

### Boot WebContainer and run npm install and dev server

Source: https://webcontainers.io/

Boot a WebContainer, mount project files, install dependencies with npm, and run the dev script. Requires the '@webcontainer/api' package and a project-files.ts module.

```TypeScript
import { WebContainer, FileSystemTree } from '@webcontainer/api';
import { projectFiles } from './project-files.ts';

async function main() {
  // First we boot a WebContainer
  const webcontainer = await WebContainer.boot();
  
  // After booting the container we copy all of our project files
  // into the container's file system
  await webcontainer.mount(projectFiles);
    
  // Once the files have been mounted, we install the project's
  // dependencies by spawning `npm install`
  const install = await webcontainer.spawn('npm', ['i']);
  
  await install.exit;
    
  // Once all dependencies have been installed, we can spawn `npm`
  // to run the `dev` script from the project's `package.json`
  await webcontainer.spawn('npm', ['run', 'dev']);
}
```

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

### Initialize terminal and pass to installDependencies and startDevServer

Source: https://webcontainers.io/tutorial/6-connect-a-terminal

Sets up the terminal instance and passes it to installDependencies and startDevServer. The terminal is created with convertEol: true and opened on terminalEl. The code boots WebContainer once, mounts files, and throws an error if installation fails.

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

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

### Directory tree example

Source: https://webcontainers.io/guides/working-with-the-file-system

Shows the file structure of a typical project with a src folder containing main.js and main.css, plus index.html and package.json at the root.

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

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

### Integrate FitAddon into terminal setup

Source: https://webcontainers.io/tutorial/7-add-interactivity

Updates the load event handler to create a FitAddon instance, load it into the terminal, and call fit() immediately after opening the terminal to ensure it fills its container. The rest of the setup (boot, mount, server-ready, startShell) remains unchanged.

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

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

### FileSystemTree example: constructing a file tree

Source: https://webcontainers.io/api

Example of constructing a FileSystemTree object with a project folder containing files, a symlink, and an empty folder. The 'bar.js' file uses a symlink to './foo.js'.

```javascript
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 WebContainer API with npm

Source: https://webcontainers.io/guides/quickstart

Run this command in your project folder to install the @webcontainer/api package.

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

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

### Create and open Terminal instance in load handler

Source: https://webcontainers.io/tutorial/6-connect-a-terminal

Creates a Terminal instance with convertEol set to true and attaches it to terminalEl. The load event handler also boots WebContainer, mounts files, installs dependencies, and starts the dev server. convertEol forces the cursor to start at the beginning of the next line.

```javascript
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();
});
```

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

### package.json - Express app manifest

Source: https://webcontainers.io/tutorial/2-setting-up-webcontainers

Package manifest for the example app. It declares Express and nodemon as dependencies and defines a start script that runs nodemon watching the current directory.

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

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

### Wait for user login before installing private packages

Source: https://webcontainers.io/api

Boots a WebContainer instance, waits for the user to be logged in using `auth.loggedIn()`, then runs `npm install` to fetch private packages. The promise from `loggedIn()` never rejects and only resolves when the user authorizes the application.

```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']);
```

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

### Replace main.js with initial content

Source: https://webcontainers.io/tutorial/1-build-your-first-webcontainer-app

Sets up the main.js file to import style.css and clear the #app element. This is the starting point for the WebContainer app.

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

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

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

### Hello from the WebContainer API

Source: https://webcontainers.io/

Example from the WebContainers landing page showing a Node.js script that uses the chalk library to print a greeting and the current Node version. Run it with `node index.js` from the terminal.

```javascript
import chalk from 'chalk';
  

console.log(chalk.magenta('Hello from the WebContainer API 👋'));
console.log(chalk.green(`Running Node ${process.version}`));
  

// Run `node index.js` from the terminal
```

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

### Call startDevServer in load event listener

Source: https://webcontainers.io/tutorial/4-running-dev-server

Adds a load event listener that boots WebContainer, mounts files, installs dependencies, and calls startDevServer(). The comment 'Call only once' warns that WebContainer.boot() should be invoked only once.

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

  startDevServer();
});
```

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

### Run npm install in WebContainer

Source: https://webcontainers.io/tutorial/3-installing-dependencies

Use webcontainerInstance.spawn('npm', ['install']) to run npm install inside a WebContainer instance. You can replace npm with pnpm or yarn.

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

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

### Stream npm install output

Source: https://webcontainers.io/tutorial/3-installing-dependencies

Use installProcess.output.pipeTo with a WritableStream to log each line of the command output to the console.

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

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

### Mount multiple files with mount

Source: https://webcontainers.io/guides/working-with-the-file-system

Defines a FileSystemTree object with package.json and index.html, then mounts it to the WebContainer instance. The example is shown in JavaScript.

```javascript
/** @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);
```

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

### spawn without args example

Source: https://webcontainers.io/api

Spawns a process without command-line arguments, here running 'yarn'.

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

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

### Pipe npm install output to terminal

Source: https://webcontainers.io/tutorial/6-connect-a-terminal

Runs npm install and pipes the process output to the terminal. The function returns the process exit code, which is used to check for installation failure.

```javascript
/**
 * @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;
}
```

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

### Install dependencies and wait for exit

Source: https://webcontainers.io/guides/running-processes

Defines an async function that installs dependencies using `npm install` and returns the exit code. The `exit` property is a promise that resolves when the process exits.

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

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

### export method example

Source: https://webcontainers.io/api

Exports the filesystem to a zip format and creates a Blob from the returned data. The method returns a FileSystemTree when format is 'json', otherwise a Uint8Array.

```javascript
const data = await webcontainerInstance.export('dist', { format: 'zip' });

const zip = new Blob([data]);
```

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

### Install Xterm.js with npm

Source: https://webcontainers.io/tutorial/6-connect-a-terminal

Installs the Xterm.js terminal frontend component, the same terminal used by Visual Studio Code and other web-based IDEs.

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

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

### Read a single file with readFile

Source: https://webcontainers.io/guides/working-with-the-file-system

Loads a single file, package.json, at the root of the file system and reads it using the readFile method. The example is shown in JavaScript.

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

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

### Watch a file

Source: https://webcontainers.io/api

Starts watching a single file for changes, logging the event type.

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

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

### index.js - Express app for WebContainer

Source: https://webcontainers.io/tutorial/2-setting-up-webcontainers

Express app entry point for the WebContainer example. It serves a welcome message at the root route and listens on port 3111, logging the live URL to the console.

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

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

### Create a WebContainer instance

Source: https://webcontainers.io/guides/quickstart

Import WebContainer and call boot() to create a WebContainer instance. The boot method can only be called once and only a single instance can be created.

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

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

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

### Make terminal responsive with shellProcess.resize on window resize

Source: https://webcontainers.io/tutorial/7-add-interactivity

Sets up the terminal with the FitAddon, boots the WebContainer, mounts files, and listens for the 'server-ready' event. On window resize, it calls fitAddon.fit() and shellProcess.resize() with the new terminal dimensions to make the terminal fully responsive.

```javascript
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,
    });
  });
});
```

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

### Install @xterm/addon-fit

Source: https://webcontainers.io/tutorial/7-add-interactivity

Installs the @xterm/addon-fit plugin for Xterm.js, which adjusts terminal columns and rows to fit its container element.

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

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

### Spawn a command with arguments

Source: https://webcontainers.io/guides/running-processes

Shows the basic usage of `webcontainerInstance.spawn` to run a command with arguments. The method takes a command string and an array of arguments.

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

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

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

### Initialize a new Vite app with the vanilla JavaScript template

Source: https://webcontainers.io/tutorial/1-build-your-first-webcontainer-app

Run this command in the terminal to create a new Vite project named 'webcontainers-express-app' using the vanilla template. This step is skipped if you're using the StackBlitz editor.

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

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

### Boot WebContainer and mount files

Source: https://webcontainers.io/tutorial/2-setting-up-webcontainers

Boots the WebContainer and mounts the files object. The mount call is highlighted as the key step for loading the project files into the container.

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

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

### readFile

Source: https://webcontainers.io/guides/working-with-the-file-system

Reads the file at the given path. If the file does not exist, it will throw an error. By default, it returns a UInt8Array, but you can pass an encoding to get a string.

```APIDOC
## readFile

### Description
Reads the file at the given path. If the file does not exist, it will throw an error.

### Method
readFile

### Endpoint
webcontainerInstance.fs.readFile(path, encoding?)

### Parameters
- **path** (string) - Required - The path to the file to read.
- **encoding** (string) - Optional - The encoding to use. If not provided, returns a UInt8Array. If 'utf-8', returns a string.

### Request Example
```js
const file = await webcontainerInstance.fs.readFile('/package.json');
//    ^ it is a UInt8Array
```

### Response
#### Success Response
- **file** (UInt8Array or string) - The contents of the file.

#### Response Example
```js
const file = await webcontainerInstance.fs.readFile('/package.json', 'utf-8');
//    ^ it is a string
```
```

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

### Boot WebContainer instance

Source: https://webcontainers.io/tutorial/2-setting-up-webcontainers

Add to main.js after the first import statement. Boots a WebContainer instance on page load, calling WebContainer.boot() only once.

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

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

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

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

### Update main.js server-ready listener

Source: https://webcontainers.io/tutorial/7-add-interactivity

Updated main.js listener for the 'server-ready' event after removing installDependencies and startDevServer methods. It boots WebContainer, mounts files, and sets the iframe source when the server is ready.

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

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

### Preview dev server in iframe

Source: https://webcontainers.io/guides/quickstart

Listens for the 'server-ready' event and sets the iframe source to the provided URL.

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

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

### Convert cd command to spawn syntax

Source: https://webcontainers.io/tutorial/3-installing-dependencies

The bash command 'cd hello-world' becomes webcontainerInstance.spawn('cd', ['hello-world']).

```bash
cd hello-world
```

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

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

### setPreviewScript method example

Source: https://webcontainers.io/api

Injects a script into all previews. After this resolves, every preview iframe added or reloaded will include the script on HTML responses. Existing previews won't include it until reloaded via reloadPreview.

```javascript
const script = `
  console.log('Hello world!');
`;

await webcontainerInstance.setPreviewScript(script);

// now all previews will always print hello world to the console if they serve HTML
```

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

### auth.startAuthFlow

Source: https://webcontainers.io/api

Initiates the OAuth authentication flow with optional popup mode.

```APIDOC
## `auth.startAuthFlow`

### Description
Starts the OAuth flow, redirecting the current page to the StackBlitz editor to authenticate the user, unless `popup` is set to true, in which case it's done in a popup.

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

### Parameters
- **options** (object) - Optional - Configuration options for the auth flow.
  - **popup** (boolean) - Optional - If true, the OAuth flow is done in a popup.
```

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

### Set references to iframe and textarea elements in main.js

Source: https://webcontainers.io/tutorial/1-build-your-first-webcontainer-app

Add this code at the bottom of main.js to get references to the iframe and textarea elements. The variables are typed as HTMLIFrameElement and HTMLTextAreaElement, allowing null. This is required before setting up WebContainers.

```javascript
/** @type {HTMLIFrameElement | null} */
const iframeEl = document.querySelector('iframe');

/** @type {HTMLTextAreaElement | null} */
const textareaEl = document.querySelector('textarea');
```

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

### mkdir creates a directory

Source: https://webcontainers.io/guides/working-with-the-file-system

Creates a directory at the given path. If the directory already exists, it will throw an error.

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

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

### Set textarea value and boot WebContainer

Source: https://webcontainers.io/tutorial/2-setting-up-webcontainers

Sets the textarea value to the contents of the index.js file and boots the WebContainer instance, mounting the file system. The comment notes that boot() should be called only once.

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

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

### auth.init

Source: https://webcontainers.io/api

Initializes the authentication API for using private packages within WebContainer.

```APIDOC
## `auth.init`

### Description
Initializes the authentication for use in WebContainer. Should be called as soon as possible during the loading phase of your page.

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

### Parameters
- **options** (AuthInitOptions) - Required - Configuration options for authentication.

### AuthInitOptions
- **editorOrigin** (string) - Optional - StackBlitz' origin. Defaults to `https://stackblitz.com`.
- **clientId** (string) - Required - The client id for this OAuth application.
- **scope** (string) - Required - OAuth scope. Found under your `Teams Settings` > `API`.

### Returns
Returns an object with `status` set to `'need-auth'` or `'authorized'`, or an `AuthFailedError`.

### AuthFailedError
- **status** (string) - Always `'auth-failed'`.
- **error** (string) - A short description of the error.
- **description** (string) - A detailed description of the error.

### Throws
Throws an exception if `WebContainer.boot` was called before `auth.init`.
```

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

### Import FitAddon

Source: https://webcontainers.io/tutorial/7-add-interactivity

Imports the FitAddon class from the @xterm/addon-fit package at the top of main.js.

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

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

### configureAPIKey

Source: https://webcontainers.io/api

Configures an API key for commercial usage, to be called before booting WebContainer.

```APIDOC
## `configureAPIKey`

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

### Signature
`configureAPIKey(key: string): void`

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

### Throws
Throws an exception if `WebContainer.boot` was called before `configureAPIKey`.
```

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

### Netlify netlify.toml for All Pages

Source: https://webcontainers.io/guides/configuring-headers

Configure headers for all pages in the netlify.toml file.

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

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

### SvelteKit: Configure headers for a specific page in hooks.server.js

Source: https://webcontainers.io/guides/configuring-headers

Use this snippet in your SvelteKit hooks.server.js file to set headers only for the /tutorial page. It checks if the request path matches '/tutorial' before setting the headers.

```JavaScript
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;
};
```

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

### mkdir

Source: https://webcontainers.io/guides/working-with-the-file-system

Creates a directory at the given path. If the directory already exists, it will throw an error. You can use the `recursive` option to create a nested folder very easily.

```APIDOC
## mkdir

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

### Method
mkdir

### Endpoint
webcontainerInstance.fs.mkdir(path, options?)

### Parameters
- **path** (string) - Required - The path to the directory to create.
- **options** (object) - Optional - Options for creating the directory.
  - **recursive** (boolean) - Optional - When true, creates nested directories.

### Request Example
```js
await webcontainerInstance.fs.mkdir('src');
```
```

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

### WebContainer

Source: https://webcontainers.io/api

The WebContainer class is the main entry point for the WebContainer API. It provides methods to boot a container instance and properties to access the file system, PATH, and working directory.

```APIDOC
## `WebContainer` class

### Description
Main export of the WebContainer library. Represents a runtime instance.

### Properties
- `fs: FileSystemAPI` - Access to the underlying file system.
- `path: string` - The default PATH environment variable for processes started through spawn.
- `workdir: string` - The full path to the working directory.

### Methods
- `static boot(options: BootOptions = {}): Promise<WebContainer>` - Boots a WebContainer.

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

#### Return
- `Promise<WebContainer>` - A promise that resolves to a WebContainer instance.

#### BootOptions
- `coep?: 'require-corp' | 'credentialless' | 'none'` - The COEP header value. If 'none', no cross-origin isolation headers are used. Only works on Chromium-based browsers with Origin Trial. Fixed after first boot.
- `workdirName?: string` - The folder name for the working directory. Auto-generated if not provided.
- `forwardPreviewErrors?: boolean | 'exceptions-only'` - Configure whether errors from preview iframes are forwarded. If 'exceptions-only', console.error calls are not forwarded. Default is false.

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

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

### mkdir

Source: https://webcontainers.io/api

Creates a new directory. If the directory already exists, it will throw an error. Options can include recursive flag to create missing folders.

```APIDOC
## `mkdir`

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

### Signature
`mkdir(path: String, options?: Options): Promise<void>`

### Options
When `recursive` is set to `true`, it will create any missing folders in the path.
ts```
interface Options {
  recursive?: boolean;
}
```

```
Tokens:
Raw