SpiderMonkey

js/ is SpiderMonkey, Mozilla's JavaScript engine. It is one of the oldest production JavaScript engines (originally written by Brendan Eich in 1996) and is the engine used by Firefox, GeckoView, the JS shell, and many embedders.

Purpose

Run JavaScript: parse source, run a baseline interpreter, JIT-compile hot code, manage memory via a generational garbage collector, expose a stable embedding C++ API, and host the WebAssembly engine.

Directory layout

js/
├── public/        # Public C++ embedding API (#include "js/...")
├── src/
│   ├── builtin/   # Built-in objects: Array, Map, Promise, RegExp, ...
│   ├── frontend/  # Parser + bytecode emitter
│   ├── vm/        # Interpreter, runtime, shape, object internals
│   ├── jit/       # Baseline interpreter, Baseline JIT, Warp/Ion JIT, CacheIR
│   ├── gc/        # Generational + incremental garbage collector
│   ├── wasm/      # WebAssembly engine
│   ├── proxy/     # Cross-realm wrappers
│   ├── jsapi-tests/
│   └── shell/     # The standalone `js` shell
├── xpconnect/     # The XPCOM ↔ JS bridge
├── loader/        # Module loader for chrome and content
└── examples/

Architecture

graph LR
    Source[JS source code] --> Parser[frontend/Parser]
    Parser --> Bytecode[Bytecode]
    Bytecode --> BaselineInt[Baseline Interpreter]
    BaselineInt --> BaselineJIT[Baseline JIT]
    BaselineJIT --> Warp[Warp + Ion JIT]
    Warp --> Native[Native code]
    BaselineInt -.->|deopt| Bytecode
    Warp -.->|bailout| BaselineJIT
    Bytecode --> ICs[CacheIR inline caches]

Tier structure

Tier	When	Role
Baseline interpreter	First execution	Interpreter generated at startup; runs all bytecodes
Baseline JIT	After warm-up	Per-function JIT, generates IC stubs
Warp + Ion	Hot functions	Optimizing compiler; speculative type assumptions
WASM Baseline / Ion	WebAssembly	Compile WASM functions; supports tiering

CacheIR (js/src/jit/CacheIR*) unifies inline cache logic across tiers. The compiler tier upgrades an IC's "stub" to compiled native code as warm-up increases.

GC

The garbage collector is generational and incremental:

• Nursery — short-lived objects (js/src/gc/Nursery.h).
• Tenured heap — long-lived; collected by major GC.
• Incremental marking — interleaved with mutator to keep pauses short.
• Cycle collection integration — JS objects and DOM objects can form cycles; the cycle collector walks both.

Embedding API

#include "jsapi.h" and the headers under js/public/. Key types:

• JSContext* — execution context (one per thread).
• JSObject* — JS object (must be rooted).
• JS::Realm — a realm (one global plus its lifetime).
• JS::Compartment — a security boundary.
• JS::Value — tagged value (number, object, string, …).

Interaction with cycle collection requires JS::Heap<> and JS::Rooted<> for stack/heap pointers respectively.

XPConnect

js/xpconnect/ bridges legacy XPCOM interfaces to JavaScript. Modern Web APIs use WebIDL bindings (dom/bindings/) instead, which are faster and type-safe.

The js shell

js/src/shell/ is a standalone REPL that links only against SpiderMonkey. Useful for engine-level testing and debugging.

cd <objdir>/dist/bin
./js script.js

WebAssembly

js/src/wasm/ implements the WebAssembly engine end-to-end: validation, compilation (Baseline + Ion), runtime, JIT exceptions, GC types, threads.

Tests

• js/src/jit-test/ — JS-level JIT tests.
• js/src/jsapi-tests/ — C++-level embedding API tests.
• Test262 — the official ECMAScript test suite, vendored under js/src/tests/.

Related

• DOM
• XPCOM