Skip to main content
Once moon has been installed, you must setup the workspace, which is denoted by the .moon folder - this is known as the workspace root. The workspace is in charge of:
  • Integrating with a version control system
  • Defining configuration that applies to its entire tree
  • Housing projects to build a project graph
  • Running tasks with the action graph

​
Initialize the Repository

Let’s scaffold and initialize moon in a repository with the moon init command. This should typically be run at the root, but can be nested within a directory. 
moon init
When executed, the following operations will be applied:
1

Create .moon folder

Creates a .moon folder with a .moon/workspace.yml configuration file.
2

Update .gitignore

Appends necessary ignore patterns to the relative .gitignore.
3

Infer VCS

Infers the version control system from the environment.
If you’re investigating moon, or merely want to prototype, you can use moon init --minimal to quickly initialize and create minimal configuration files.

​
Workspace Configuration

The .moon/workspace.yml file is the central configuration for your moon workspace. Here’s a basic example:
.moon/workspace.yml
$schema: './cache/schemas/workspace.json'

projects:
  - 'apps/*'
  - 'packages/*'

vcs:
  client: 'git'
  defaultBranch: 'main'

​
Configure Project Discovery

moon supports two approaches for discovering projects in your workspace:

​
Configure Version Control System

moon requires a version control system (VCS) to be present for functionality like file diffing, hashing, and revision comparison. The VCS and its default branch can be configured through the vcs setting:
.moon/workspace.yml
vcs:
  client: 'git'
  defaultBranch: 'main'
moon defaults to git with a default branch of master, so you only need to configure this if your setup differs.

​
Migrate from Existing Build Systems

Looking to migrate from Nx or Turborepo to moon? Use our migration commands for a seamless transition: 
moon ext migrate-nx
These extensions will convert your existing configuration files to moon’s format as best as possible.

​
Workspace Structure

After initialization, your workspace will have the following structure: 
.
├── .moon/
│   ├── cache/
│   ├── workspace.yml
│   └── tasks/           # Optional: Global task configurations
├── apps/
│   ├── web/
│   │   └── moon.yml     # Project-specific configuration
│   └── api/
│       └── moon.yml
├── packages/
│   └── shared/
│       └── moon.yml
└── .gitignore

​
Verify Setup

You can verify your workspace is configured correctly by running: 
moon project-graph --json
This will display all discovered projects in your workspace.

​
Next Steps

Create a Project

Configure individual projects in your workspace

Workspace Configuration

Learn about all available workspace configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us