Appearance

Return to top
On this page

API Reference

The public WebContainer API allows you to build custom applications on top of an in-browser Node.js runtime. Its main entry point is the WebContainer class.

WebContainer

The main export of this library. An instance of WebContainer represents a runtime ready to be used.

WebContainer Properties


fs: FileSystemAPI

Gives access to the underlying file system.

WebContainer Methods

▸ boot

Boots a WebContainer. Only a single instance of WebContainer can be booted.

Signature

static boot(): Promise<WebContainer>

Return

Returns a WebContainer instance.

▸ mount

Mounts a FileSystemTree into the file system.

Signature

mount(tree: FileSystemTree, options?: Options): Promise<void>

Options

ts
interface Options {
  mountPoint?: string;
}

▸ on

Listens for an event. The listener is called every time the event gets emitted.

Signature


on(event: 'port' | 'error' | 'server-ready', listener: PortListener | ErrorListener | ServerReadyListener): () => void


Returns

Returns a function to unsubscribe from the events. Once unsubscribed, the listener will no longer be called.


Overloads


▸ on(event: 'port', listener: PortListener): () => void

Listens for port events, which are emitted when a port is opened or closed by some process.

PortListener (Function)

ts
(port: number, type: "open" | "close", url: string): void

▸ on(event: 'error', listener: ErrorListener): () => void

Listens for error events, emitted when an internal error is triggered.

ErrorListener (Function)

ts
(error: { message: string }): void

▸ on(event: 'server-ready', listener: ServerReadyListener): () => void

Listens for server-ready events, emitted when a server was started and ready to receive traffic.

ServerReadyListener (Function)

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

▸ spawn

Spawns a process. When no args are provided, spawns a process without command-line arguments.

Signature

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

Example

With args:

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

Without args:

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

Returns

Returns a WebContainerProcess.


Overloads


▸ spawn(command: string, args: string[], options?: SpawnOptions): () => void

Spawns a process with additional arguments.

▸ spawn(command: string, options?: SpawnOptions): () => void

Spawns a process without additional arguments.

▸ teardown

Destroys a WebContainer instance and releases its resources.

Signature

teardown(): void

DirEnt

A representation of a directory entry, see the Node.js API.

DirEnt Properties


▸ name

The name of the file or directory.

Signature

name: string | Uint8Array

DirEnt Methods

▸ isDirectory

Whether the entry is a directory.

Signature

isDirectory(): boolean

▸ isFile

Whether the entry is a file.

Signature

isFile(): boolean

FileSystemAPI

Interface to interact directly with the WebContainer file system. Modeled after fs.promises in Node.

FileSystemAPI Methods

▸ mkdir

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

▸ readdir

Reads a given directory and returns an array of its files and directories.

Signature

readdir(path: string, options?: Options): Promise<Uint8Array[]> | Promise<string[]> | Promise<DirEnt<Uint8Array>[]> | Promise<DirEnt<string>[]>

Options

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

encoding: BufferEncoding

The encoding (see BufferEncoding) can be any one of those accepted by Buffer.


withFileTypes: boolean

When set to true, the return value is an array of Dirent objects.

▸ readFile

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

Signature

readFile(path: string, encoding?: BufferEncoding | null): Promise<Uint8Array> | Promise<string>

By default, it returns a UInt8Array. A second argument can be passed as the encoding.

Example

Without encoding:

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

With a specified encoding:

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

Returns

Promise<Uint8Array> or Promise<string>

▸ rm

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, including nested folders.

Signature

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

Options

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

force?: boolean

When true, exceptions will be ignored if the path does not exist.

recursive?: boolean

If true, it will recursively remove directories, including nested directories.

Example

Deleting a file:

js
await webcontainerInstance.fs.rm('/src/main.js');

Deleting a directory:

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

▸ writeFile

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.

Signature

writeFile(path: string, data: string | Uint8Array, options?: string { encoding?: null | BufferEncoding } | null): Promise<void>

Example

Default:

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

With encoding:

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

FileSystemTree

A tree-like structure to describe the contents of a folder to be mounted.

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

Also see FileNode and DirectoryNode.

Example

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

FileNode

ts
interface FileNode {
  file: {
    contents: string | Uint8Array;
  };
}

FileNode Properties


▸ file: { contents: string | Uint8Array }

Represents a file with contents. Also see FileSystemTree.

DirectoryNode

ts
interface DirectoryNode {
  directory: FileSystemTree;
}

DirectoryNode Properties


▸ directory: FileSystemTree

Represents a directory node. Also see FileSystemTree.

SpawnOptions

Options that control spawning a process.

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

SpawnOptions Properties


▸ env?: Record<string, string | number | boolean>

Environment variables to set for the process.


▸ output?: boolean

When set to false, no terminal output is sent back to the process, and the output stream will never produce any chunks.


▸ terminal?: { cols: number; rows: number }

The size of the attached terminal.

WebContainerProcess

A running process spawned in a WebContainer instance.

WebContainerProcess Properties


▸ exit: Promise<number>

A promise for the exit code of the process.


▸ input: WritableStream<string>

An input stream for the attached pseudoterminal device.


▸ output: ReadableStream<string>

A stream that receives all terminal output, including the stdout and stderr emitted by the spawned process and its descendants.

Can be disabled by setting output to false via spawn.

Signature

output: ReadableStream<string>

WebContainerProcess Methods

▸ kill

Kills the process.

Signature

kill(): void

▸ resize

Resizes the attached terminal.

Signature

resize(dimensions: { cols: number, rows: number }): void

BufferEncoding

ts
type BufferEncoding =
  | 'ascii'
  | 'utf8'
  | 'utf-8'
  | 'utf16le'
  | 'ucs2'
  | 'ucs-2'
  | 'base64'
  | 'base64url'
  | 'latin1'
  | 'binary'
  | 'hex'
  | 'buffer';

Was this page helpful?