retrobasic-wasm

Run classic BASIC programs wherever JavaScript runs. retrobasic-wasm packages the RetroBASIC interpreter as a zero-dependency, single-file WebAssembly bundle. Perfect for preserving vintage BASIC software and running retro text games like The Oregon Trail, Hammurabi, Lunar Lander, and Super Star Trek directly in Node.js or modern browsers.

Install

npm install retrobasic-wasm

Requires Node.js 18 or later. This is an ESM-only package; use import, not require().

Usage

Node.js

import { runBasic } from "retrobasic-wasm";

const exitCode = await runBasic({
  source: `
    10 PRINT "Hello from WASM!"
    20 END
  `,
  onStdout: (line) => console.log(line),
});

Browser

import { runBasic } from "retrobasic-wasm";

const response = await fetch("/program.bas");
const source = await response.text();

const outputElement = document.getElementById("terminal");

await runBasic({
  source,
  onStdout: (line) => {
    if (outputElement) outputElement.textContent += line + "\n";
  },
});

Interactive input

Programs that use INPUT can receive user input via the stdin option. Each entry is one input line; a trailing newline is added when needed.

import { runBasic } from "retrobasic-wasm";

const exitCode = await runBasic({
  source: `
    10 INPUT "What is your name? "; N$
    20 PRINT "Hello, "; N$; "!"
    30 END
  `,
  stdin: ["Alice"],
  onStdout: (line) => console.log(line),
});

API

runBasic(options: RunBasicOptions): Promise<number>

Runs a BASIC program via WebAssembly.

| Option | Type | Description | | ---------- | ------------------------ | ------------------------------------------------------ | | source | string | The BASIC program source code | | onStdout | (line: string) => void | Called for each line of standard output | | onStderr | (line: string) => void | Called for each line of standard error | | stdin | readonly string[] | Input lines fed to INPUT statements, one per element |

stdin also accepts a readonly array, so a frozen array or TypeScript tuple is valid. runBasic creates a fresh interpreter for every call, making concurrent calls isolated.

Returns the interpreter exit code — 0 typically indicates success; non-zero indicates an interpreter error or STOP. Errors while loading or initializing the WebAssembly module reject the promise.

onStdout and onStderr receive one newline-free line at a time. Render a newline yourself when writing those values to a terminal or DOM element.

Types

type BasicOutputHandler = (line: string) => void;

interface RunBasicOptions {
  source: string;
  stdin?: readonly string[];
  onStdout?: BasicOutputHandler;
  onStderr?: BasicOutputHandler;
}

The package exports runBasic, RunBasicOptions, and BasicOutputHandler.

Compatibility

RetroBASIC implements its own BASIC dialect. Program compatibility depends on the statements and extensions a program uses; this package exposes the interpreter rather than translating BASIC to JavaScript.

Demo

The repository includes an interactive browser demo running The Oregon Trail, Hammurabi, Lunar Lander, and Super Star Trek.

Development

Building the WASM binary requires Emscripten, Bison, and Flex.

# From the repository root
npm install

# Build the WASM binary, then re-bundle dist/ against it
npm run build:wasm
npm run build

# Start the Vite dev server (demo)
npm run dev

# Run format, lint, and test
npm run all

License

This package is licensed under GPL-2.0-only. It includes a modified WebAssembly build of RetroBASIC; copyright and complete-source information are in NOTICE. The corresponding source and build scripts are available in the Basicade repository.