Skip to main content
A workspace is a directory that contains projects, manages a toolchain, runs tasks, and is coupled with a VCS repository. The root of a workspace is denoted by a .moon folder.

​
Overview

The workspace is the foundation of your moon setup. It serves as the central hub where:
  • All projects are discovered and managed
  • Global configuration is defined
  • Toolchain versions are specified
  • Shared tasks are configured
  • Cache and build artifacts are stored
By default, moon has been designed for monorepos, but can also be used for polyrepos.

​
Directory Structure

When you initialize a moon workspace, the following structure is created: 
workspace-root/
├── .moon/
│   ├── workspace.yml       # Workspace-level configuration
│   ├── toolchains.yml      # Toolchain version management
│   ├── tasks/              # Global task configurations
│   │   ├── node.yml
│   │   └── bash.yml
│   └── cache/              # Build cache and artifacts
│       ├── hashes/
│       ├── outputs/
│       └── states/
├── projects/               # Your projects
│   ├── app/
│   ├── api/
│   └── shared/
└── package.json            # Root package.json (for Node.js)

​
Configuration

Workspace configuration is defined in .moon/workspace.yml. This file controls workspace-wide settings that affect all projects.

​
Basic Configuration

.moon/workspace.yml
$schema: './cache/schemas/workspace.json'

# Default project to use when none specified
defaultProject: 'website'

# Project discovery
projects:
  # Explicit sources
  sources:
    api: 'packages/api'
    web: 'apps/web'
  
  # Glob patterns for auto-discovery
  globs:
    - 'packages/*'
    - 'apps/*'
    - '!apps/legacy'  # Exclude specific paths

# VCS configuration
vcs:
  defaultBranch: 'main'
  provider: 'git'

# Pipeline settings
pipeline:
  logRunningCommand: true

​
Project Discovery

Moon supports two ways to define projects:
  1. Explicit sources - Manually define each project with its path
  2. Glob patterns - Automatically discover projects using glob patterns
.moon/workspace.yml
projects:
  # Explicit mapping of project IDs to paths
  sources:
    designSystem: 'packages/design-system'
    apiClients: 'packages/api-clients'
  
  # Auto-discovery with globs
  globs:
    - 'packages/*'
    - 'apps/*'
    - '!packages/cli'  # Exclude patterns
Glob patterns are evaluated relative to the workspace root. Use ! prefix to exclude specific paths.

​
Monorepo vs Polyrepo

In a monorepo setup, all projects live within a single workspace: 
monorepo/
├── .moon/
├── packages/
│   ├── ui/
│   ├── utils/
│   └── api/
└── apps/
    ├── web/
    └── mobile/
Benefits:
  • Shared toolchain versions across all projects
  • Unified task inheritance
  • Efficient caching and dependency management
  • Simplified CI/CD pipelines

​
Polyrepo

For polyrepo setups, each repository can have its own moon workspace: 
repo-1/
└── .moon/
    └── workspace.yml

repo-2/
└── .moon/
    └── workspace.yml
In polyrepo mode, you lose some benefits like cross-project task dependencies and shared caching, but gain repository independence.

​
Workspace Features

​
VCS Integration

Moon integrates with your version control system to enable features like affected detection:
.moon/workspace.yml
vcs:
  defaultBranch: 'main'
  provider: 'git'
  hooks:
    pre-commit:
      - 'moon run :lint'
      - 'moon run :typecheck'

​
Remote Caching

Configure remote caching to share build artifacts across machines and CI environments:
.moon/workspace.yml
remote:
  host: 'grpcs://cache.example.com'
  auth:
    token: 'CACHE_TOKEN'
  cache:
    verifyIntegrity: true
    compression: 'zstd'

​
Pipeline Configuration

Control how tasks are executed in the pipeline:
.moon/workspace.yml
pipeline:
  logRunningCommand: true
  concurrency: 8

​
Generator Templates

Define paths to code generation templates:
.moon/workspace.yml
generator:
  templates:
    - './.moon/templates'
    - './shared-templates'

​
Environment Variables

Moon provides several environment variables that are automatically available in the workspace:
  • MOON_VERSION - The version of moon being used
  • MOON_WORKSPACE_ROOT - Absolute path to the workspace root
  • MOON_CACHE_DIR - Path to the cache directory

​
Best Practices

Group related projects together using a consistent directory structure. Common patterns include:
  • apps/ for applications
  • packages/ for libraries
  • tools/ for internal tooling
Instead of manually listing every project, use glob patterns for automatic discovery. This makes it easier to add new projects without updating workspace config.
Commit .moon/workspace.yml, .moon/toolchains.yml, and .moon/tasks/ to version control. Add .moon/cache/ to .gitignore.
Define common tasks once in .moon/tasks/ and inherit them across projects. This reduces duplication and ensures consistency.
  • Projects - Individual projects within the workspace
  • Toolchain - Version management for tools and languages
  • Tasks - Commands that run in projects
  • Cache - Build caching and artifact management

​
Configuration Reference

For detailed configuration options, see:

Build docs developers (and LLMs) love

Get started for freeTalk to us