A high-performance Ahead-Of-Time (AOT) compiler compiling TypeScript to native standalone executables and WebAssembly (WASI) modules with Node.js core subset parity.
ScriptGo is a high-performance native compiler that runs TypeScript and JavaScript with Node.js-compatible semantics while compiling eligible code directly to standalone native binaries or WebAssembly modules. It combines the official TypeScript (Go implementation) compiler frontend for parsing, type-checking, and diagnostics with an independent Typed IR system and an LLVM IR / Native Machine Code backend.
Highlights & Features
- High-Performance AOT Compilation: Compiles TypeScript directly to native machine code (Mach-O, ELF, PE) and WebAssembly (
.wasm) via LLVM.
- Node.js Core Subset Parity: All 437 regression corpus cases match their expected output; 435/437 also match Node.js v22 (two decorator-metadata cases differ only because Node's type stripping emits no metadata).
- test262 Tracking:
cmd/test262 measures a 25k-test ECMAScript subset (4,154 pass, 23.6% of attempted); the core subset is curated, so most of test262 is still rejected or unsupported (see the parity report). CI runs a recorded passing baseline as a regression gate.
- WebAssembly / WASI Target: First-class Ahead-Of-Time compilation to standalone
.wasm executables with --target wasm32-wasi, validated on Node.js WASI and Wasmtime.
- Zero-Dependency Native Builds: Automatically uses system
clang or auto-detects zig cc for hassle-free out-of-the-box compilation and seamless cross-compilation (macOS, Linux, Windows, WASM).
- Fast Execution: Instantly compiles and runs scripts directly or produces optimized standalone binary builds.
- Modern TypeScript & ECMAScript (ES2022 - ES2025):
- Explicit Resource Management: Full
using and await using resource disposal with Symbol.dispose and Symbol.asyncDispose.
- ES2024 Set Methods:
union(), intersection(), difference(), symmetricDifference(), isSubsetOf(), isSupersetOf(), isDisjointFrom().
- ES2024 Utilities:
Promise.withResolvers(), Object.groupBy(), Map.groupBy(), Array.fromAsync().
- ES2025 Iterator Helpers:
Iterator.from(), map(), filter(), take(), drop(), flatMap(), reduce(), toArray(), forEach(), some(), every(), find().
- Types & Primitives:
number (IEEE-754), bigint, string (UTF-8), boolean, symbol (with Symbol Registry), null, undefined, unknown (with type narrowing), Tuples, Enums (numeric, string, reverse mappings), Union types (T | null | undefined), Monomorphized Generics.
- Control Flow:
if/else, switch/case (with fallthrough), while, do..while, for, for..of, for..in, for await..of, Labeled statements (break label, continue label), try/catch/finally, throw, Array & Object destructuring, Spread/Rest (...), Tagged template literals, Optional chaining & calls (?., fn?.()).
- Functions & Closures: Lexical closures, arrow functions, default/optional/rest parameters, Generators (
function*, yield, yield*), Async Generators.
- OOP & Classes: Constructors, properties, static fields/methods, Class Static Blocks (), Getters/Setters, Inheritance (, ), Polymorphic VTables, .
Documentation
docs/typescript-parity-report.md - Core subset feature matrix, corpus parity, and test262 conformance results.docs/native-subset.md - Native static subset definition and compatibility constraints.docs/compilation-tiers.md - Static, Dynamic (QuickJS-ng island), and Unsupported compilation policy.docs/application-structure.md - Repository architecture, package ownership, and dependency direction.docs/typescript-to-native.md - Pipeline boundaries, IR verification invariants, and LLVM lowering.docs/stdlib.md - Standard library API scope and Node.js runtime emulation policy.docs/roadmap.md - Project roadmap, milestones, and acceptance criteria.
Installation
Install the latest GitHub release on macOS or Linux:
curl -fsSL https://raw.githubusercontent.com/pilotworks/scriptgo/main/install.sh | sh
Install a specific release or choose another destination:
curl -fsSL https://raw.githubusercontent.com/pilotworks/scriptgo/main/install.sh | \
sh -s -- --version 0.1.0-alpha.1 --install-dir /usr/local/bin
The installer detects the host platform, downloads the matching release
archive, verifies it against SHA256SUMS, and installs the scriptgo binary.
The default destination is ~/.scriptgo; add that directory to PATH if
needed. A Clang-compatible native toolchain is still required to compile
TypeScript programs.
Run the same command again to upgrade the existing installation to the latest
release. The installer verifies and atomically replaces the current binary.
CLI Usage
Running Code
# Compile and run immediately on host
scriptgo run examples/hello.ts
# Run with inline TypeScript code
scriptgo run -e "console.log('Hello from ScriptGo!')"
Building Standalone Executables & WebAssembly Modules
# 1. Build a native binary for the host platform
scriptgo build examples/hello.ts -o hello
# 2. Build a WebAssembly (WASI) module
scriptgo build --target wasm32-wasi examples/hello.ts -o hello.wasm
# 3. Execute the generated WASM module via Node.js WASI or Wasmtime
node -e 'const { WASI } = require("wasi"); const fs = require("fs"); const wasi = new WASI({ version: "preview1", args: ["hello.wasm"], returnOnExit: true }); const bytes = fs.readFileSync("hello.wasm"); (async () => { const mod = await WebAssembly.compile(bytes); const inst = await WebAssembly.instantiate(mod, wasi.getImportObject()); wasi.start(inst); })();'
# Or via wasmtime
wasmtime hello.wasm
# 4. Build with debug symbols
scriptgo build examples/hello.ts --debug -o hello-debug
# 5. Build with Clang sanitizers (address, undefined, leak)
scriptgo build examples/hello.ts --sanitize address,undefined -o hello-sanitized
Type Checking & Emitting IR
# Type-check and validate against the native subset
scriptgo check examples/hello.ts
# Emit LLVM IR
scriptgo emit examples/hello.ts -o hello.ll
# Emit verified Typed IR
scriptgo emit examples/hello.ts --mode typed-ir -o hello.ir
Showcase Examples
Explore the examples/ directory for complete TypeScript samples:
examples/hello.ts - Basic hello world script.examples/fibonacci.ts - Recursive and iterative performance benchmark.examples/classes_oop.ts - OOP with inheritance, class static blocks, getters/setters, and instanceof.examples/functional_arrays.ts - Functional Array methods (map, filter, reduce, find, some, every).examples/advanced_primitives.ts - BigInt, Symbol registry, and RegExp literals.examples/async_generators.ts - Generator functions, async generators, and for await..of loops.examples/node_apis.ts - Built-in Node.js APIs (path, crypto, fs, os).
Toolchain & Cross-Compilation
ScriptGo uses a Clang-compatible C/LLVM compiler driver to compile emitted LLVM IR and link against the lightweight runtime:
- System Clang: Defaults to
clang in your $PATH.
- Zig CC (
zig cc): If clang is not installed or when compiling for cross targets (including --target wasm32-wasi), ScriptGo automatically utilizes zig in $PATH for zero-dependency builds and cross-compilation across platforms.
Configuring Compiler Driver & Target Triple
You can configure the C compiler driver and target triple via CLI flags or environment variables:
# 1. WebAssembly / WASI compilation
scriptgo build examples/hello.ts --target wasm32-wasi -o hello.wasm
# 2. Cross-compilation for Linux x86_64
scriptgo build examples/hello.ts --cc zigcc --target x86_64-linux-gnu -o hello-linux
# 3. Via environment variables
export SCRIPTGO_CC="zigcc"
export SCRIPTGO_TARGET="wasm32-wasi"
scriptgo build examples/hello.ts -o hello.wasm
Direct Cross-Compilation via zig cc
You can also emit LLVM IR and cross-compile with zig cc directly:
# 1. Emit LLVM IR
scriptgo emit examples/hello.ts -o module.ll
# 2. Cross-compile for Linux x86_64
zig cc -target x86_64-linux-gnu -O2 -x ir module.ll -x c internal/runtime/runtime.c -o hello-linux
# 3. Cross-compile for Windows x86_64
zig cc -target x86_64-windows-gnu -O2 -x ir module.ll -x c internal/runtime/runtime.c -o hello-windows.exe
# 4. Cross-compile for macOS ARM64
zig cc -target aarch64-macos -O2 -x ir module.ll -x c internal/runtime/runtime.c -o hello-macos
Development & Contributing
We welcome contributions! Please check out CONTRIBUTING.md to get started.
# Build binary
make build
# Run all unit & integration tests
make test
# Run TypeScript-Go frontend tests
make test-frontend
# Run Node.js parity comparison benchmark
make test-parity
Community & Security
License
This project is licensed under the MIT License.
