Skip to main content
moon is the monorepo management tool. It is used to define and execute common tasks across all projects in the monorepo, including build, test, lint, and type-checking tasks. moon helps streamline workflows across multiple projects and ensures tasks are executed consistently.
Refer to the official documentation for more details.

​
Concepts

​
Project

A project is a library, application, package, binary, tool, etc, that contains source files, test files, assets, resources, and more. A project must exist and be configured within a workspace.

​
Workspace

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

​
Tasks

Tasks are commands that are ran in the context of a project. Underneath the hood, a task is simply a binary or system command that is ran as a child process.

​
Toolchain

The toolchain is an internal layer for downloading, installing, and managing tools (languages, dependency managers, libraries, and binaries) that are required at runtime. We embrace this approach over relying on these tools “existing” in the current environment, as it ensures the following across any environment or machine:
  • The version and enabled features of a tool are identical.
  • Tools are isolated and unaffected by external sources.
  • Builds are consistent, reproducible, and hopefully deterministic.
Furthermore, this avoids a developer, pipeline, machine, etc, having to pre-install all the necessary tools, and to keep them in sync as time passes.

​
Targets

A target is a compound identifier that pairs a scope to a task, separated by a :, in the format of scope:task. Targets are used by terminal commands… 
moon run designSystem:build
And configurations for declaring cross-project or cross-task dependencies. 
tasks:
  build:
    command: 'webpack'
    deps:
      - 'designSystem:build'

​
Usage

​
Tasks

You can use moon to manage tasks for projects across the monorepo.
  1. Running Tasks for a Specific Project:
    You can run tasks such as build or test for specific projects within the monorepo. To do this, specify the project name before the task you want to run. For example:
  • To run tests for the portal application:
moon portal:test
  • To build the portal application:
moon portal:build
  1. Running Tasks Across All Projects:
    If you want to run a task across all projects in the monorepo, you can do so without specifying a project. For example, to build all projects:
moon :build
  1. Listing Available Tasks for Projects
    If you want to list all available tasks across all projects in the monorepo, you can run:
moon query tasks

​
TypeScript

The TypeScript toolchain automates and maintains the consistency of project references across our monorepo, reducing manual TypeScript config management and preventing import resolution issues for developers. By handling project reference creation, inclusion, synchronization, and path alias mapping automatically, our team can focus on coding rather than configuration maintenance.
Refer to the project references guide for more details.

​
Automatically creates missing tsconfig.json files

If a project we depend on doesn’t have a tsconfig.json, moon generates one automatically. This ensures the project can participate in TypeScript project references and avoids manual setup.

​
Ensures editors see referenced project source files

moon adds the source folders of referenced projects to the include field of our tsconfig.json. This makes sure editor features like IntelliSense, auto-imports, and jump-to-definition work correctly across projects.

​
Keeps project references in sync with dependencies

Dependencies between projects are automatically reflected in tsconfig.json project references—both at the project level and the root. This keeps TypeScript aware of how our internal packages depend on one another.

​
Adds path aliases for internal projects

Project references are also mapped to TypeScript path aliases using their package.json names. This lets us import with stable, clear names (like @telgea/api) and ensures those aliases point to the actual source code.

​
Projects

​
Automatically installs dependencies before running tasks

Before running any task, moon verifies that our language dependencies (e.g., node_modules for TypeScript or virtual environments for Python) are up to date. If it detects changes in lockfiles or manifest files—by comparing their modified timestamps, parsing manifests, and hashing the resolved dependency versions—it automatically installs any missing or updated packages. This applies to both TypeScript and Python projects. If no changes are found, the install step is skipped.