Just Bash

Shell adapter for wterm, powered by just-bash. Provides line editing, tab completion, command history, and a colored prompt — all running in the browser with no backend.

Install

npm install @wterm/just-bash just-bash

just-bash is a peer dependency.

Quick Start

import { useCallback, useRef } from "react";
import { Terminal, useTerminal } from "@wterm/react";
import { BashShell } from "@wterm/just-bash";
import "@wterm/react/css";

function App() {
  const { ref, write } = useTerminal();
  const shellRef = useRef<BashShell | null>(null);

  const handleReady = useCallback(() => {
    if (shellRef.current) return;
    const shell = new BashShell({
      files: { "/home/user/hello.txt": "Hello, world!\n" },
      greeting: "Welcome to wterm!",
    });
    shellRef.current = shell;
    shell.attach(write);
  }, [write]);

  const handleData = useCallback((data: string) => {
    shellRef.current?.handleInput(data);
  }, []);

  return (
    <Terminal
      ref={ref}
      onReady={handleReady}
      onData={handleData}
    />
  );
}

Use a ref to hold the BashShell instance so it's accessible from both the onReady and onData callbacks.

Options

Option	Type	Default	Description
`files`	`Record<string, string>`	`{}`	Virtual filesystem (keys are absolute paths, values are file contents)
`env`	`Record<string, string>`	`{ SHELL, TERM }`	Environment variables
`cwd`	`string`	`"/home/user"`	Initial working directory
`greeting`	`string \| string[]`	—	Lines printed when the shell attaches
`prompt`	`(cwd: string) => string`	colored `user@wterm:~$`	Custom prompt function — receives the current working directory
`network`	`NetworkConfig`	—	Network access configuration (see Network Access)

Methods

Method	Description
`attach(write): Promise<void>`	Connect to a terminal write function. Loads just-bash, prints the greeting, and displays the initial prompt.
`handleInput(data): Promise<void>`	Process terminal input (keystrokes, paste). Call this from the terminal's `onData` callback.

Properties

Property	Type	Description
`cwd`	`string`	Current working directory (updates after `cd`)
`bash`	`Bash \| null`	Underlying just-bash instance (`null` until `attach` completes)

Virtual Filesystem

The files option populates an in-memory filesystem. Keys are absolute paths, values are file contents:

const shell = new BashShell({
  files: {
    "/home/user/README.md": "# My Project\n\nHello, world!\n",
    "/home/user/src/main.zig": 'const std = @import("std");\n',
    "/home/user/data/config.json": '{ "key": "value" }\n',
  },
});

Directories are created implicitly from file paths. Commands like ls, cat, cd, and pwd work against this virtual filesystem.

Network Access

By default, the shell runs fully offline. To enable network access (for commands like curl or fetch), pass the network option from just-bash:

const shell = new BashShell({
  network: {
    dangerouslyAllowFullInternetAccess: true,
  },
});

The NetworkConfig type is re-exported from just-bash. See the just-bash documentation for all available network options.

Keyboard Shortcuts

Key	Action
`Tab`	Autocomplete files and commands
`Up` / `Down`	Navigate command history
`Left` / `Right`	Move cursor within the current line
`Ctrl+A`	Jump to start of line
`Ctrl+E`	Jump to end of line
`Ctrl+U`	Clear the current line
`Ctrl+C`	Cancel current input
`Ctrl+L`	Clear screen
`\` at end of line	Line continuation (multi-line input)