MoonRepo Commands: A Practical Guide to dev, build, lint, and More

monorepobuild-systemclitooling

MoonRepo provides a powerful command-line interface for managing tasks across your monorepo. This guide covers the essential commands you'll use daily for development, building, linting, and managing your projects.

Understanding MoonRepo Task Syntax

MoonRepo uses a consistent syntax for running tasks:

moon run [project]:[task]
  • Project: The name of the project (e.g., web, api, ui)
  • Task: The task name defined in moon.yml (e.g., dev, build, lint)

You can also use wildcards and patterns to run tasks across multiple projects.

Development Commands

Running Development Servers

Start a development server for a specific project:

# Next.js app
moon run web:dev

# Astro app
moon run astro-app:dev

# Hono API
moon run api:dev

MoonRepo will:

  • Check dependencies and build them if needed
  • Start the development server with hot reload
  • Watch for file changes and rebuild as necessary

Running Multiple Development Servers

To run multiple apps simultaneously, use separate terminals or background processes:

# Terminal 1
moon run web:dev

# Terminal 2
moon run astro-app:dev

# Terminal 3
moon run api:dev

Or use background processes:

moon run web:dev & moon run astro-app:dev & moon run api:dev

Build Commands

Building a Single Project

Build a specific project:

# Build Next.js app
moon run web:build

# Build Astro app
moon run astro-app:build

# Build API
moon run api:build

MoonRepo automatically:

  • Builds dependencies first (if needed)
  • Uses cached outputs when inputs haven't changed
  • Only rebuilds what's necessary

Building All Projects

Build all projects in the monorepo:

moon run :build

The : prefix means "all projects". MoonRepo will:

  • Analyze the dependency graph
  • Build projects in the correct order
  • Parallelize independent builds
  • Skip projects that haven't changed (if using cache)

Building Multiple Specific Projects

Build specific projects by listing them:

moon run web:build astro-app:build

Linting and Code Quality

Lint a Single Project

# Lint Next.js app
moon run web:lint

# Lint API
moon run api:lint

Lint All Projects

moon run :lint

This runs linting across all projects that have a lint task defined.

Auto-fix Linting Issues

Many projects define a lint:fix task:

moon run web:lint:fix

Type Checking

Type Check a Project

# Type check Next.js app
moon run web:typecheck

# Type check all projects
moon run :typecheck

TypeScript projects typically define a typecheck task that runs tsc --noEmit to verify types without generating output files.

Testing

Run Tests

# Run tests for a specific project
moon run ui:test

# Run all tests
moon run :test

Watch Mode

Many test tasks support watch mode:

moon run ui:test:watch

Advanced Task Patterns

Running Tasks with Dependencies

MoonRepo automatically handles task dependencies. When you run:

moon run web:build

MoonRepo will:

  1. Check if web depends on other projects (like @workspace/ui)
  2. Build those dependencies first
  3. Then build web

Using Task Dependencies

Tasks can depend on other tasks:

# moon.yml
tasks:
  build:
    deps:
      - '^build'  # Build all dependencies first
      - '~:typecheck'  # Type check current project first
    command: 'next build'

The ^ prefix means "dependencies", and ~ means "current project".

Running Tasks in Parallel

MoonRepo automatically parallelizes independent tasks. When you run:

moon run :build

Projects without dependencies on each other will build simultaneously, significantly reducing total build time.

Project Management

View Project Graph

Visualize your project dependencies:

moon project-graph

This shows:

  • All projects in your monorepo
  • Dependency relationships
  • Project types (application, library, tool)

List All Projects

moon project list

View Project Details

Get detailed information about a specific project:

moon project view web

Cache Management

Understanding MoonRepo Caching

MoonRepo caches task outputs based on:

  • Input files (source code, config files)
  • Task dependencies
  • Environment variables (if configured)

Checking Cache Status

# See cache statistics
moon cache status

# View cache for a specific task
moon cache view web:build

Clearing Cache

# Clear all cache
moon clean

# Clear cache for a specific project
moon clean web

# Clear cache for a specific task
moon clean web:build

Cache Invalidation

Cache is automatically invalidated when:

  • Input files change
  • Dependencies change
  • Task configuration changes
  • Environment variables change (if tracked)

Task Configuration

Viewing Task Configuration

See how a task is configured:

moon task web:build

This shows:

  • Command being run
  • Dependencies
  • Input/output files
  • Environment variables
  • Cache settings

Common Task Patterns

Development Server:

tasks:
  dev:
    command: 'next dev --turbopack'
    local: true  # Don't cache local dev servers

Build Task:

tasks:
  build:
    command: 'next build'
    deps: ['~:typecheck']
    inputs:
      - '**/*'
      - '.env*'
    outputs:
      - '.next/**'
      - '!.next/cache/**'

Lint Task:

tasks:
  lint:
    command: 'next lint'
    inputs:
      - '**/*.{ts,tsx,js,jsx}'

Type Check Task:

tasks:
  typecheck:
    command: 'tsc --noEmit'
    inputs:
      - '**/*.{ts,tsx}'
      - 'tsconfig.json'

Filtering and Targeting

Run Tasks for Multiple Projects

# Build all apps
moon run :build --filter=apps/*

# Build all packages
moon run :build --filter=packages/*

Run Tasks Based on Tags

If projects have tags defined:

# moon.yml
tags: ['frontend', 'next']

You can target them:

moon run :build --tag=frontend

Run Tasks for Changed Projects

# Only build projects that changed
moon run :build --affected

Environment Variables

Setting Environment Variables

# For a single run
NODE_ENV=production moon run web:build

# In moon.yml
tasks:
  build:
    env:
      NODE_ENV: 'production'

Environment Variable Caching

To make cache sensitive to environment variables:

tasks:
  build:
    env:
      NODE_ENV: 'production'
    envFile: '.env.production'  # Track env file changes

Common Workflows

Daily Development

# Start all dev servers
moon run web:dev & moon run astro-app:dev & moon run api:dev

# In another terminal, run linting
moon run :lint

# Type check before committing
moon run :typecheck

Pre-Commit Checks

# Run all quality checks
moon run :lint
moon run :typecheck
moon run :test

CI/CD Pipeline

# Install dependencies
pnpm install

# Type check
moon run :typecheck

# Lint
moon run :lint

# Build all projects
moon run :build

# Run tests
moon run :test

Production Build

# Build everything
moon run :build

# Start production servers
cd apps/web && pnpm start
cd apps/astro-app && pnpm preview
cd apps/api && pnpm start

Troubleshooting

Task Not Found

If you get "task not found":

  1. Check the project name: moon project list
  2. Check task definition: moon task [project]:[task]
  3. Verify moon.yml exists in the project directory

Cache Issues

If builds seem stale:

# Clear cache and rebuild
moon clean
moon run :build

Dependency Issues

If dependencies aren't building:

# Check dependency graph
moon project-graph

# Force rebuild dependencies
moon run ^build

Performance Issues

If tasks are slow:

  1. Check cache status: moon cache status
  2. Verify inputs/outputs are configured correctly
  3. Check if tasks are running in parallel: moon run :build --verbose

Best Practices

  1. Define Clear Inputs/Outputs: This enables effective caching
  2. Use Task Dependencies: Let MoonRepo handle build order
  3. Leverage Parallelization: Design tasks to run independently when possible
  4. Cache Appropriately: Don't cache local dev servers (local: true)
  5. Use Tags: Organize projects with tags for easier targeting
  6. Track Environment Variables: Include env files in inputs when they affect builds

Conclusion

MoonRepo's command system provides a powerful and intuitive way to manage tasks across your monorepo. By understanding the syntax and patterns, you can efficiently develop, build, test, and deploy your projects. The intelligent caching and dependency management mean you spend less time waiting and more time coding.

Whether you're running a single dev server or building an entire monorepo, MoonRepo's commands give you the control and performance you need to scale your development workflow.