Prebuilt Node.js Sidecar for Land 🏞️

VS Code ships one Node.js binary and detects the platform at runtime, with fallback chains that fail in edge cases - Alpine Linux, custom glibc versions, ARM configurations. SideCar packages the exact Node.js binary for each target triple at compile time, so Cocoon always gets the binary that matches the host. No runtime detection, no fallback chains, no surprises.

"The right binary, for the right platform, at the right time."

Rust API Documentation 📖

SideCar is the prebuilt Node.js sidecar repository for the Land Code Editor. It packages platform-specific Node.js binaries organized by target triple so that Cocoon - Land's Node.js extension host - receives the exact runtime binary that matches the target platform. SideCar replaces runtime detection and fallback chains with a single deterministic lookup at build time.

VS Code ships one Node.js binary and detects the platform at runtime - a strategy that breaks on Alpine Linux, custom glibc versions, and ARM configurations. SideCar eliminates this class of failure entirely by bundling the correct binary per target triple at compile time.

SideCar is engineered to:

1. Provide Portable Runtimes - Ship vendored Node.js binaries that eliminate user dependency requirements and system-Node.js coupling.
2. Enable Deterministic Builds - Organize binaries by target triple for build-time binary selection with no runtime detection.
3. Support Multiple Platforms - Comprehensive matrix for macOS, Linux, and Windows on x86_64 and aarch64 architectures.
4. Automate Download Management - Automated fetching, caching, and Git LFS management of runtime binaries via the Download Rust tool.

Deterministic Binary Selection - Binaries are organized by target triple (aarch64-apple-darwin/, x86_64-unknown-linux-gnu/, etc.). Mountain's build.rs selects the correct binary at compile time - Cocoon receives a path, never a guess.

Concurrent Downloads - The Download Rust binary uses Tokio for parallel fetching of multiple runtime binaries from nodejs.org, maximizing throughput across the full platform matrix.

Intelligent Caching - Cache.json tracks downloaded versions per target triple. Subsequent runs skip already-fetched binaries, avoiding redundant downloads and enabling incremental updates.

Version Resolution - Automatic resolution of major versions (e.g., 22) to the latest patch release from nodejs.org distribution feeds. No manual version pinning required.

Git LFS Integration - Automatic .gitattributes management for large binary tracking. The Download tool updates Git LFS pointers, keeping the repository lean while binaries remain accessible.

Platform Matrix - Full coverage for x86_64 and aarch64 across macOS (apple-darwin), Linux (unknown-linux-gnu), and Windows (pc-windows-msvc).

graph LR
    classDef sidecar   fill:#d0d8ff,stroke:#4a6fa5,stroke-width:2px,color:#001050;
    classDef external  fill:#ebebeb,stroke:#888,stroke-width:1px,stroke-dasharray:5 5,color:#333;
    classDef storage   fill:#cce8ff,stroke:#2980b9,stroke-width:1px,color:#003050;
    classDef mountain  fill:#f0d0ff,stroke:#9b59b6,stroke-width:2px,color:#2c0050;
    classDef cocoon    fill:#d0f0d0,stroke:#27ae60,stroke-width:1px,color:#0a3a0a;

    subgraph SOURCES["External Sources"]
        NodeJSOrg["nodejs.org official distributions"]:::external
    end

    subgraph SIDECAR["SideCar 🏍️ - Prebuilt Node.js Sidecar"]
        direction TB
        subgraph TOOL["Source/ - Download Tool (Rust binary)"]
            DownloadBin["Download.rs ⬇ fetch · verify · organise Tokio parallel downloads"]:::sidecar
            CacheJSON["Cache.json 💾 version tracking skip redundant downloads"]:::sidecar
            GitLFS[".gitattributes 📦 Git LFS pointers for large binaries"]:::sidecar
            DownloadBin --> CacheJSON
            DownloadBin --> GitLFS
        end
        subgraph LAYOUT["Target-Triple Layout"]
            Darwin_ARM["aarch64-apple-darwin/ 🍎 Apple Silicon"]:::storage
            Darwin_x86["x86_64-apple-darwin/ 🖥 macOS Intel"]:::storage
            Win_x86["x86_64-pc-windows-msvc/ 🪟 Windows x64"]:::storage
            Win_ARM["aarch64-pc-windows-msvc/ 🪟 Windows ARM64"]:::storage
            Linux_ARM["aarch64-unknown-linux-gnu/ 🐧 Linux ARM64"]:::storage
            Linux_x86["x86_64-unknown-linux-gnu/ 🐧 Linux x64"]:::storage
        end
        BuildRS["build.rs 🔧 binary selection at build time stages correct triple into installer"]:::sidecar

        DownloadBin --> LAYOUT
        BuildRS --> LAYOUT
    end

    subgraph CONSUMERS["Consumers at Runtime"]
        Mountain["Mountain ⛰️ build.rs bundles chosen binary into Tauri installer"]:::mountain
        Cocoon["Cocoon 🦋 receives correct Node.js binary no runtime detection needed"]:::cocoon
    end

    NodeJSOrg --> DownloadBin
    LAYOUT --> BuildRS
    BuildRS --> Mountain
    Mountain -- spawns with Spawn.rs --> Cocoon

Data flow paths:

Element/SideCar/
├── Source/
│   ├── Download.rs              # Main download binary: fetch, verify, organize
│   ├── Library.rs               # Module declarations and shared utilities
│   └── main.rs                  # Binary entry point
├── build.rs                     # Build script: binary selection and staging
├── Cache.json                   # Download cache metadata (version tracking)
├── .gitattributes               # Git LFS pointer rules for large binaries
├── Resource/
│   └── dns-override.js          # DNS resolution customization resource
├── aarch64-apple-darwin/        # macOS Apple Silicon binaries
├── x86_64-apple-darwin/         # macOS Intel binaries
├── x86_64-pc-windows-msvc/      # Windows x64 binaries
├── aarch64-pc-windows-msvc/     # Windows ARM64 binaries
├── aarch64-unknown-linux-gnu/   # Linux ARM64 (glibc) binaries
├── x86_64-unknown-linux-gnu/    # Linux x64 (glibc) binaries
├── Temporary/                   # Temporary workspace for downloads
├── Documentation/
│   ├── GitHub/                  # GitHub-specific documentation
│   │   ├── Architecture.md      # Detailed architecture document
│   │   └── DeepDive.md          # Technical deep-dive
│   └── Rust/                    # Cargo doc output
└── Cargo.toml

SideCar vendored binaries are the compile-time source of truth for Cocoon's Node.js runtime. During the application build, Mountain's build.rs orchestrator selects the correct binary from SideCar based on the target triple. Cocoon receives a deterministic path - no runtime detection, no fallback chains, no platform-specific edge cases.

The Download Rust binary populates the SideCar directory structure once during project setup by fetching official distributions from nodejs.org and organizing them by target triple convention. Subsequent runs only fetch new or updated versions.

• Rust 1.75 or later
• Git LFS installed and configured (for binary tracking)

cd Element/SideCar
cargo build --release

# Fetch and organize all platform binaries
./Target/release/Download

The SideCar directory is populated once during project setup:

1. Build Download Tool: Compile the Download binary from Source/Download.rs
2. Run Download: Execute to fetch and organize all runtime binaries
3. Build Mountain: The build system selects appropriate binaries from SideCar at compile time

[!NOTE] The target-triple directories (aarch64-apple-darwin/, x86_64-unknown-linux-gnu/, etc.) are populated by the Download Rust binary and contain large, third-party binaries. These directories should not be committed directly to version control - use Git LFS via the auto-managed .gitattributes file. The Download tool should be run once to vendor the dependencies as part of the initial project setup.

SideCar enforces binary integrity at multiple layers:

SideCar is designed to integrate with:

• Rust API Documentation 📖

• Architecture Overview - Land system architecture
• Why Rust - Why Rust for the download tooling
• Mountain - Native desktop shell
• Cocoon - Node.js extension host

This project is funded through NGI0 Commons Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet program, under grant agreement No 101135429.

The project is operated by PlayForm, based in Sofia, Bulgaria. PlayForm acts as the open-source steward for Code Editor Land under the NGI0 Commons Fund grant.