Andromeda

A modern, fast(eventually), and secure JavaScript & TypeScript runtime built from the ground up in Rust 🦀 and powered by Nova Engine and Oxc.

Andromeda provides zero-config TypeScript support, rich Web APIs, and native performance for scripts, utilities, and applications that need to run fast without the complexity of traditional Node.js setups.

Join our Discord community to discuss ideas and get involved!

Key Features

• Run TypeScript files directly with zero configuration or transpilation.
• Resolve bare specifiers and CDN imports with Import Maps.
• Create web servers and APIs with the built-in HTTP server.
• Draw with the GPU-accelerated Canvas API, backed by WGPU with PNG export.
• Use industry-standard cryptographic primitives through the Web Crypto API.
• Work with databases through built-in SQLite support.
• Read and write files through the file system APIs.
• Persist data with localStorage and sessionStorage.
• Run JavaScript with Nova's Rust-powered engine.
• Use the developer tools for interactive evaluation, formatting, and compilation.
• Identify performance bottlenecks with the hotpath profiler.
• Access web APIs including TextEncoder, TextDecoder, and Performance.
• Customize the runtime through optional extensions.
• Stay current with the built-in upgrade system.
• Enable shell completion for bash, zsh, fish, and PowerShell.

Standards & Compatibility

Andromeda aims to be WinterTC compliant, ensuring interoperability and compatibility with the broader JavaScript ecosystem. WinterTC provides a test suite for JavaScript engines to ensure they conform to ECMAScript standards and common runtime behaviors.

Note: ⚠️ Andromeda is in active development. While functional, it's not yet recommended for production use.

Quick Start

Installation

Platform specific instructions:

Linux/Mac:

curl -fsSL https://tryandromeda.dev/install.sh | bash

Windows (PowerShell):

irm -Uri "https://tryandromeda.dev/install.ps1" | Invoke-Expression

Windows (CMD):

curl -L -o install.bat https://tryandromeda.dev/install.bat && install.bat

Install Andromeda using Cargo:

cargo install --git https://github.com/tryandromeda/andromeda andromeda

Install Andromeda using winget:

winget install --id Andromeda.Andromeda

Running Code

Execute JavaScript or TypeScript files directly:

# Run a TypeScript file (no compilation needed!)
andromeda run hello.ts

# Run multiple files
andromeda run script1.js script2.ts

# Run with verbose output
andromeda run --verbose my-script.ts

Example: Hello World with Canvas

// Create a simple drawing
const canvas = new OffscreenCanvas(400, 300);
const ctx = canvas.getContext("2d")!;

ctx.fillStyle = "#ff6b6b";
ctx.fillRect(50, 50, 100, 100);

ctx.fillStyle = "#4ecdc4";
ctx.beginPath();
ctx.arc(200, 150, 50, 0, Math.PI * 2);
ctx.fill();

// Save as PNG
canvas.saveAsPng("output.png");
console.log("Image saved to output.png");

Example: Standard Library

import { Queue } from "https://tryandromeda.dev/std/collections/mod.ts";
import { flatten } from "https://tryandromeda.dev/std/data/mod.ts";

const queue = new Queue();
queue.enqueue("first");
queue.enqueue("second");
console.log(queue.dequeue());
console.log(queue.size);

console.log(flatten([[1, 2], [3, [4, 5]]], 1));
console.log(flatten([[1, 2], [3, [4, 5]]], 2));

Core APIs

File System

// Read and write files synchronously
const content = Andromeda.readTextFileSync("input.txt");
Andromeda.writeTextFileSync("output.txt", content.toUpperCase());

// and asynchronously
const contentAsync = await Andromeda.readTextFile("input.txt");
await Andromeda.writeTextFile("output.txt", contentAsync.toUpperCase());

// Access environment variables
const home = Andromeda.env.get("HOME");
Andromeda.env.set("MY_VAR", "value");

Canvas & Graphics

// Create graphics programmatically
const canvas = new OffscreenCanvas(800, 600);
const ctx = canvas.getContext("2d")!;

// Draw with full Canvas 2D API
ctx.fillStyle = "linear-gradient(45deg, #f093fb, #f5576c)";
ctx.fillRect(0, 0, 800, 600);

// Export to PNG
canvas.saveAsPng("artwork.png");

Web Storage

// localStorage and sessionStorage APIs
localStorage.setItem("user-preference", "dark-mode");
const preference = localStorage.getItem("user-preference");
console.log("Stored items:", localStorage.length);

// Session storage for temporary data
sessionStorage.setItem("session-id", crypto.randomUUID());
const sessionId = sessionStorage.getItem("session-id");

Cryptography

// Generate secure random values
const uuid = crypto.randomUUID();
const randomBytes = crypto.getRandomValues(new Uint8Array(32));

// Hash data
const data = new TextEncoder().encode("Hello, World!");
const hash = await crypto.subtle.digest("SHA-256", data);

Performance Monitoring

// High-precision timing
const start = performance.now();
await someAsyncOperation();
const duration = performance.now() - start;

// Performance marks and measures
performance.mark("operation-start");
await doWork();
performance.mark("operation-end");
performance.measure("total-time", "operation-start", "operation-end");

Web Workers

Run JavaScript or TypeScript on a separate OS thread. Andromeda implements the WHATWG dedicated Worker API with module workers, structured-clone messaging, and MessageChannel/MessagePort.

// worker.ts
self.onmessage = (event) => {
  self.postMessage({ doubled: (event.data as number) * 2 });
};

// main.ts
const worker = new Worker(
  new URL("./worker.ts", import.meta.url),
  { type: "module" },
);

worker.onmessage = (event) => {
  console.log(event.data); // { doubled: 84 }
  worker.terminate();
};

worker.postMessage(42);

In-realm message passing with MessageChannel:

const channel = new MessageChannel();
channel.port1.onmessage = (e) => console.log("port1 got:", e.data);
channel.port2.postMessage("hello");

Database Operations

const db = new Database(":memory:");

const stmt = db.prepare("INSERT INTO users (name, email) VALUES (?, ?)");
stmt.run("Alice", "alice@example.com");

const users = db.prepare("SELECT * FROM users").all();
console.log(users);

db.close();

Developer Experience

Interactive REPL

Andromeda includes a powerful REPL with enhanced developer experience:

# Start the interactive REPL
andromeda repl

REPL Features:

• Read TypeScript with syntax highlighting and keyword recognition.
• Enter multiline functions and objects with automatic incomplete-syntax detection.
• View execution timing for each evaluation.
• Navigate command history with the arrow keys.
• Use help, history, clear, gc, and exit to manage the session.
• Complete JavaScript and TypeScript expressions with context-aware suggestions.

Code Formatting

Format TypeScript and JavaScript files with the built-in formatter:

# Format specific files
andromeda fmt script.ts utils.js

# Format entire directories
andromeda fmt src/ examples/

# Format current directory
andromeda fmt

Single-File Compilation

Compile your scripts into standalone executables:

# Create a single-file executable
andromeda compile my-script.ts my-app.exe

# Run the compiled executable directly
./my-app.exe

Language Server Protocol (LSP)

Andromeda includes a built-in Language Server that provides real-time diagnostics and linting capabilities for JavaScript and TypeScript files in your editor:

# Start the Language Server (typically called by your editor)
andromeda lsp

LSP Features:

• See diagnostics as you type.
• Find common code quality issues with built-in lint rules:
  • Empty function detection
  • Empty statement detection
  • Variable usage validation
  • Unreachable code detection
  • Invalid syntax highlighting
• Analyze files across the workspace.
• Read error explanations alongside their source context.
• Integrate with VS Code, Neovim, and other LSP-compatible editors.

Configure your editor to use andromeda lsp as the language server for JavaScript and TypeScript files to get instant feedback on code quality.

Shell Integration

Generate completion scripts for your shell:

# Auto-detect shell and generate completions
andromeda completions

# Generate for specific shells
andromeda completions bash > /etc/bash_completion.d/andromeda
andromeda completions zsh > ~/.zsh/completions/_andromeda
andromeda completions fish > ~/.config/fish/completions/andromeda.fish
andromeda completions powershell > $PROFILE/andromeda.ps1

Self-Updating

Keep Andromeda up to date with the built-in upgrade system:

# Upgrade to latest version
andromeda upgrade

# Force reinstall current version
andromeda upgrade --force

# Upgrade to specific version
andromeda upgrade --version 0.1.0-draft-49

# Preview what would be upgraded
andromeda upgrade --dry-run

Task System

Andromeda includes a powerful task system inspired by Deno, allowing you to define and run custom scripts and workflows directly from your configuration file.

Defining Tasks

Tasks are defined in your andromeda.json, andromeda.toml, or andromeda.yaml configuration file:

{
  "tasks": {
    "dev": "andromeda run src/main.ts",
    "build": "echo Building project...",
    "test": "andromeda run tests/main.ts",
  }
}

Running Tasks

# List all available tasks
andromeda task

# Run a specific task
andromeda task dev
andromeda task build
andromeda task test

Architecture & Extensions

Andromeda is built with a modular architecture, allowing features to be enabled or disabled as needed:

Runtime Extensions

Extension	Description	APIs Provided
Canvas	GPU-accelerated 2D graphics	OffscreenCanvas, CanvasRenderingContext2D, ImageBitmap with WGPU backend
Crypto	Web Crypto API implementation	crypto.subtle, crypto.randomUUID(), crypto.getRandomValues()
Console	Enhanced console output	console.log(), console.error(), console.warn()
Fetch	HTTP client capabilities	fetch(), Request, Response, Headers
File System	File I/O operations	Andromeda.readTextFileSync(), Andromeda.writeTextFileSync(), directory ops
Local Storage	Web storage APIs	localStorage, sessionStorage with persistence
Process	System interaction	Andromeda.args, Andromeda.env, Andromeda.exit()
SQLite	Database operations	Database, prepared statements, transactions
Time	Timing utilities	performance.now(), setTimeout(), setInterval(), Andromeda.sleep()
URL	URL parsing and manipulation	URL, URLSearchParams
Web	Web standards	TextEncoder, TextDecoder, navigator, queueMicrotask()
Workers	Off-thread JS execution	Worker, DedicatedWorkerGlobalScope (self.postMessage/close), MessageChannel, MessagePort
Window (optional)	Native OS windowing (winit)	Andromeda.Window, Andromeda.createWindow(), DOM-style events, rawHandle()

Window extension (optional, behind window feature)

The window feature adds Andromeda.Window, a native OS window backed by winit on macOS, Windows, and Linux (X11/Wayland). Inspired by deno-windowing/dwm, the class extends EventTarget and dispatches DOM-style events (resize, close, keydown, keyup, mousemove, mousedown, mouseup).

const win = Andromeda.createWindow({ title: "Hello", width: 640, height: 480 });
win.addEventListener("keydown", (e) => {
  if ((e as CustomEvent).detail.code === "Escape") win.close();
});
await Andromeda.Window.mainloop();

Enable the feature:

cargo run --features window -- run examples/window.ts

window.rawHandle() returns a { system, windowHandle, displayHandle, width, height } object compatible with Deno.UnsafeWindowSurface for future WebGPU-surface bridges.

When the canvas feature is also enabled, window.presentCanvas(canvas) blits an OffscreenCanvas's latest frame into the window via a shared wgpu device without CPU readback or size restrictions. examples/window.ts demonstrates a live 2D scene streamed from an OffscreenCanvas into a winit-backed window. examples/breakout.ts is a keyboard-driven Breakout clone exercising the full window + canvas input/render pipeline.

Andromeda Satellites

Satellites are minimal, purpose-built executables designed for containerized environments and microservice architectures. Each satellite focuses on a single capability, providing smaller container images, faster startup times, and better resource utilization.

Available Satellites

• andromeda-run executes JavaScript/TypeScript in production containers.
• andromeda-compile compiles JS/TS to executables.
• andromeda-fmt formats code.
• andromeda-lint checks code for quality issues.
• andromeda-bundle bundles and minifies code.

Crates

Crate	Description
andromeda	Command-line interface and developer tools
andromeda-core	Core runtime engine and JavaScript execution
andromeda-runtime	Runtime extensions and Web API implementations

Contributing

Andromeda is an open-source project and welcomes contributions! Whether you're interested in:

• Fixing bugs to improve stability
• Adding runtime capabilities
• Improving guides and examples
• Expanding test coverage

Join our Discord community to discuss ideas and get involved!

License

Mozilla Public License Version 2.0