How moonrepo/moon works
Project type and purpose
• moon is a polyglot monorepo management/orchestration CLI tool (written in Rust) with supplemental JavaScript/TypeScript packages and a documentation website.
• Its core delivers: config loading, project & task graph construction, action pipelines, remote caching, toolchain management, plugins, and notifications.
High-level file-structure analysis
Top-level:
• crates/… ⇢ Rust workspace of ~150 crates (config, project-graph, task-graph, action-pipeline, runner, remote, plugin host, toolchain detection, etc.).
• packages/… ⇢ npm/yarn workspaces supplying TypeScript libraries (cli wrappers, runtime, types, report, visualizer).
• website/… ⇢ React/Docusaurus/Vite/Tailwind docs site.
• moon.yml, package.json, Cargo.toml ⇢ workspace manifests.
Patterns: layered Rust libraries compose engine; a small binary crate (crates/cli and crates/app) wires together engine modules. Node packages expose JS APIs & CLI shims. The website is a standalone frontend.
Key README insights
• Emphasizes Rust-based performance, incremental adoption, multi-platform support.
• Features align with components: hashing (task-hasher), remote caches (crates/remote), toolchain (crates/toolchain), graphs (crates/project-graph, crates/task-graph), pipelines (crates/action-pipeline), plugins (wasm & crates/plugin), notifications (crates/notifier, git hooks).
a. Main components
– User CLI Frontend:
• Binary (‘moon’): crates/cli + crates/app
– Configuration Layer:
• Config loader & cache: crates/config
– Discovery & Modeling:
• Workspace & project discovery: crates/workspace
• Project graph builder: crates/project-graph
• Task graph builder: crates/task-graph & crates/task-builder
– Execution Orchestration:
• Action pipeline (dependencies + thread-pool): crates/action-pipeline
• Task runner (command execution, caching, hydration): crates/task-runner
– Toolchain & Environment:
• Detect & install toolchains: crates/toolchain + crates/toolchain-plugin
• Env var management: crates/env-var
– Cache & Remote Services:
• Local cache engines: crates/cache, crates/cache-item
• Remote cache client & service (HTTP/gRPC): crates/remote
– Plugin infrastructure:
• WASM plugin host & registry: crates/plugin + wasm/…
– Notifications & Git hooks:
• Notifier & webhooks: crates/notifier
• Git hooks generator: crates/vcs-hooks
– JS/TS API layer (for embedding & wrappers): packages/types, packages/runtime, packages/cli, packages/report, packages/visualizer
– Documentation Website: website/… (React + Docusaurus)
b. Relationships & data flows
1. User invokes moon CLI → binary loads config → builds workspace & project graph → builds task graph → action pipeline schedules jobs → task-runner executes (spawns processes with detected toolchains & environment).
2. During execution, runner consults local cache; misses trigger remote client to fetch/push via HTTP or gRPC.
3. Plugins (WASM) can be invoked by pipeline for custom steps.
4. Notifier emits terminal notifications & optional webhooks.
5. JS packages wrap the Rust CLI or expose programmatic APIs.
6. Website is independent, consumes static schemas & MDX, no direct runtime coupling.
c. Architectural patterns & principles
• Layered architecture: Config → Discovery → Graph → Pipeline → Runner
• Modular crates: Each concern (hashing, graph, runner) is its own library crate.
• Plugin architecture: WASM + extension plugin registry
• Micro-services style remote cache (HTTP/gRPC)
• Language-platform abstraction: toolchain detection, environment isolation
• Separation of concerns: Rust engine vs JS wrapper vs website
d. Notable technologies
– Rust (tokio, serde, prost for gRPC)
– WASM for plugins
– Node.js / TypeScript / Yarn 4 (CLI shim & runtime packages)
– React + Docusaurus + Tailwind for website
– CI workflows: GitHub Actions, Docker