monox

README

monox

Polyglot Monorepo Management for Modern Stacks

Features • Installation • Quick Start • Stack Guides • Commands • Configuration • Security • Contributing

---

monox is a high-performance monorepo tool written in Go. It blends the developer experience of Nx, the rigor of Bazel, and the speed of Turborepo while staying truly polyglot. Discover projects automatically, run tasks in parallel, and ship faster with hermetic caching.

Build once. Cache everywhere. Ship every stack with one binary.

Beta notice: monox is currently in public beta. Advanced features such as remote/cloud cache backends and distributed execution are still being validated—please test in non-production environments before rolling out widely.

✨ Features

Core platform

Capability	Details
Performance	Single static binary (Go) with zero runtime dependencies
Smart cache	Content-addressable cache with local + remote backends (S3, GCS)
Graph brain	Automatic dependency graph + Bazel-like queries (deps, rdeps, allpaths)
Parallelism	Task scheduler that respects dependencies and boundaries
Affected mode	Git-based change detection for incremental CI
Polyglot engine	First-class Go, Python, React, Angular, Next.js with plugin SDK for more

Developer experience

• monox init to scaffold workspaces with sensible defaults
• monox generate for stack-specific blueprints
• monox graph --dot for DOT/JSON graphs that plug into any viz
• monox watch for continuous rebuild/test
• VS Code extension: project tree, task runner, generators, cache controls

Enterprise extras

• Module boundary linting with tag rules
• Remote execution hooks
• SBOM + container builds via GoReleaser
• Signed artifacts, Homebrew/Scoop taps, Docker images, and GHCR publishing

Feature comparison

Capability	monox	Nx	Turborepo	Bazel
Single static binary	✅	❌	❌	❌
Polyglot (Go, Python, JS)	✅	⚠️ (JS-first)	⚠️ (JS-first)	✅
Automatic project discovery	✅	✅	✅	❌
Remote cache (S3/GCS)	✅ (beta)	✅	✅	✅
Module boundary linting	✅	✅	❌	✅
Bazel-style query language	✅	⚠️ limited	❌	✅
Code generators	✅	✅	❌	❌
VS Code extension	✅	✅	❌	❌
Hermetic sandboxing	✅	❌	❌	✅
Distributed execution hooks	✅	⚠️ cloud	❌	✅

Legend: ✅ = native, ⚠️ = partial/limited, ❌ = missing.

---

📦 Installation

Method	Command
Homebrew	brew install deadlock-labs/tap/monox
Go toolchain	go install github.com/deadlock-labs/monox/cmd/monox@latest
Scoop (Windows)	scoop bucket add monox https://github.com/deadlock-labs/scoop-bucket.git && scoop install monox
Binaries	Download from Releases

Build from source:

git clone https://github.com/deadlock-labs/monox.git
cd monox
go build -o monox ./cmd/monox
sudo mv monox /usr/local/bin/

---

🚀 Quick Start

monox init                     # create workspace config
monox list                     # discover projects
monox run build                # run build everywhere
monox run test --affected=main # only changed projects
monox graph --dot | dot -Tsvg  # visualize dependencies
monox generate go:app api      # scaffold service

---

🧱 Stack Guides

Go

monox generate go:app api-service --tags=backend,api
monox generate go:lib shared-utils --directory=libs

• Auto-detects modules, replace directives, CGO
• Tasks inferred for build, test, vet, lint
• Cross-compilation ready via GoReleaser profile
• Sample structure: apps/api-service/{main.go,project.yaml}

Python

monox generate python:app ml-service --package ml_service
monox generate python:lib data-utils --directory=libs

• Supports Poetry, pip, pipenv, uv
• Inferred tasks: pytest, mypy, ruff, black
• Virtualenv isolation with .venv per project
• Dependency graph built from pyproject, requirements, imports

React

monox generate react:app dashboard --style=tailwind --typescript
monox generate react:lib ui-kit --publishable

• Vite or Webpack bundlers
• Tailwind, CSS Modules, Styled Components presets
• Vitest + Testing Library wired in
• ESLint + Prettier configs shared via workspace generators

Next.js

monox generate next:app website --app-router --style=tailwind
monox generate next:app legacy --app-router=false

• Next 14 with App Router by default (Pages optional)
• Turbopack-ready dev server tasks
• API routes + middleware templates
• SWC config optimized for monorepo builds

Angular

monox generate angular:app admin --routing --style=scss
monox generate angular:lib shared-ui --publishable

• Standalone components (Angular 17+) or NgModules
• ESLint, Karma/Jest, Cypress optional tasks
• Strict TypeScript config and style linting
• Nx-compatible project.json for easy migration

---

📋 Commands

Command	Purpose
monox init	Bootstrap workspace config
monox list	See detected projects and tasks
monox run <task>	Run tasks with caching/parallelism
monox affected	Calculate impacted projects since git refs
monox graph	Print dependency graph (ascii/json/dot)
monox generate	Scaffold stacks (go/python/react/next/angular)
monox watch	Re-run tasks on file change
monox cache	Inspect/clean caches
monox query	Bazel-style graph queries
monox lint	Enforce module boundaries
monox migrate	Dependency upgrade insights

---

⚙️ Configuration

Workspace file (monox.yaml):

version: 1
name: my-monorepo

discovery:
  include:
    - "apps/*"
    - "libs/*"
  exclude:
    - "node_modules"
    - ".git"

cache:
  enabled: true
  local: .monox/cache
  remote:
    type: s3
    bucket: my-monox-cache
    region: us-east-1

parallel: 0

globalInputs:
  - monox.yaml
  - package-lock.json

targetDefaults:
  build:
    dependsOn: ["^build"]
    cache: true
  test:
    dependsOn: ["build"]

Project file (project.yaml):

name: api-service
type: application
tags: [backend, type:app]

tasks:
  build:
    command: go
    args: ["build", "-o", "bin/api", "./cmd/api"]
    inputs: ["**/*.go", "go.mod", "go.sum"]
    outputs: ["bin"]
  test:
    command: go
    args: ["test", "./..."]

Remote cache examples are in docs/cache.md (coming soon).

---

🔐 Security

• Report vulnerabilities via SECURITY.md
• Sign releases with GoReleaser cosign integration
• CI runs govulncheck, npm audit, pip-audit

---

🤝 Contributing

We love contributions! Read CONTRIBUTING.md then:

git clone https://github.com/deadlock-labs/monox.git
cd monox
go test ./...
monox run lint

Open a PR with clear description, tests, and documentation updates. See CODE_OF_CONDUCT.md for community standards.

---

📄 License

This project is licensed under the MIT License.

---

Built with care by the monox community • Star us