Cottontail

Cottontail is a small Zig-based JavaScript and TypeScript runtime built for Electrobun. It uses JavaScriptCore and implements the Node and Bun APIs that application workloads need.

Responsibilities

Cottontail runs scripts, resolves installed modules, provides runtime APIs, drains async work, runs tests, and exposes the compiler entry point used by Hutch.

Hutch owns project scripts, dependencies, toolchains, version selection, and Electrobun orchestration. Cottontail does not mutate application projects or act as their package manager.

Runtime components

Optional standard-library features are private runtime components, not npm packages. Each build emits bin/cottontail-stdlib/capabilities.json from the final component bundles. The manifest contains only canonical component names and their runtime dependencies:

{
  "schema": 1,
  "capabilities": {
    "archive": { "requires": ["compression"] },
    "compression": { "requires": [] }
  }
}

The complete graph inherits the exact Cottontail release version. Hutch reads the manifest when assembling an application and includes the transitive requires closure; application dependencies remain a separate, npm-compatible package-manager graph.

Build

A fresh checkout requires Node.js 24. The setup scripts download the pinned Zig, JavaScriptCore, and zig-html-rewriter artifacts and verify their checksums. macOS builds also require Xcode or Command Line Tools and CMake. Setup builds pinned static OpenSSL, libffi, Brotli, and Zstandard sources for the macOS 14 baseline and caches them under vendors/macos-deps.

node scripts/setup.js
node scripts/setup-zig-html-rewriter.js
node scripts/setup-jsc.js
node scripts/zig.js build

The binary is written to zig-out/bin/cottontail.

After the first build, Cottontail can drive the repository scripts itself:

./zig-out/bin/cottontail scripts/repo.js build
./zig-out/bin/cottontail scripts/repo.js test
./zig-out/bin/cottontail scripts/repo.js bench
./zig-out/bin/cottontail scripts/repo.js run test.js

Test

# Zig and JavaScript runtime suites
bun run test

# Runtime plus Electrobun bridge and CLI suites
bun run test:blocking

# Imported Node and Bun compatibility suites
bun run compat:upstream

See cross-platform compatibility for the current platform matrix and known gaps.

Local Electrobun development

With a sibling Electrobun checkout built at ../electrobun/package/dist:

bun run test:electrobun
bun run test:electrobun:cli
bun run electrobun:window

The direct bridge is for local integration work. Production Electrobun builds select and package Cottontail through the versioned Electrobun devkit.

Prebuilt releases support macOS 14 or later on arm64 and Intel x64, Linux x64 and arm64, and Windows x64 and arm64. Release CI verifies JavaScriptCore JIT tiers and WebAssembly on both macOS architectures and Windows ARM64. See cross-platform bring-up for native build diagnostics.