Install moon
The following guide can be used for adding moon to an existing repository (with incremental adoption), or to a fresh repository. All that's required is...
- Node.js and basic knowledge of the ecosystem
- git, a version control system
- A
package.json
in your repository root
- New repo
- Existing repo
git init ./app
cd ./app
npm init
If you already have a root package.json
, continue to the next section, otherwise...
npm init
Choosing a package manager
Before we install moon, we should briefly talk about Node.js package managers. To start, moon does
not replace a package manager, nor does it apply any "magic" for them to work differently. Instead,
moon builds upon a package manager to provide a robust build system, assumes a standard
node_modules
layout and module resolution algorithm, and supports any of the following 3 package
managers.
We suggest Yarn 3 for its powerful workspaces implementation, extensive support for native binaries, built-in package patching, and blazing speed, but feel free to choose the one that works best for you!
Enabling workspaces
moon was built with monorepos in mind, and as such, has first-class support for them through package workspaces (but is not a requirement). To utilize workspaces, enable them for your chosen package manager.
- Yarn
- Yarn (classic)
- npm
- pnpm
{
// ...
"workspaces": ["apps/*", "packages/*"]
}
# ...
nodeLinker: 'node-modules'
{
// ...
"workspaces": ["apps/*", "packages/*"]
}
{
// ...
"workspaces": ["apps/*", "packages/*"]
}
packages:
- 'apps/*'
- 'packages/*'
Installing the CLI
The entirety of moon is packaged and shipped as a single binary through the @moonrepo/cli
npm
package. Begin by installing this package at the root of the repository.
- Yarn
- Yarn (classic)
- npm
- pnpm
yarn add --dev @moonrepo/cli
yarn add --dev @moonrepo/cli
# If using workspaces
yarn add --dev -W @moonrepo/cli
npm install --save-dev @moonrepo/cli
pnpm add --save-dev @moonrepo/cli
# If using workspaces
pnpm add --save-dev -w @moonrepo/cli
Accessing the moon
binary
For developers, we suggest installing the @moonrepo/cli
package globally, so that you can easily
run moon
commands from any directory, instead of relying on package.json
scripts. When using
this approach, the global must be installed with npm (not pnpm or yarn)!
npm install -g @moonrepo/cli
Don't worry though, when using the global binary, we ensure the same version of moon is being executed that was defined as a dependency in the repo.
Adding a package script
For other scenarios or environments, like CI, moon
can be ran with through a package.json
script
-- but this comes with a cost -- which is the overhead of launching Node.js and your chosen package
manager to execute the Rust binary, instead of executing the Rust binary directly. If this is
problematic, feel free to use the global approach above.
{
// ...
"scripts": {
// ...
"moon": "moon",
// For Yarn 2+
"moon": "$(yarn bin moon)"
}
}
caution
Yarn 2+ does not support executing Rust binaries through package scripts (issue), so we must access the full binary path and execute on that.
With this script, moon can then be run with npm run moon ...
(or yarn run
, or pnpm run
), but
do note that this pattern will not work with package workspaces unless the script is ran from the
repository root.
Supported targets
Because moon is written in Rust, we only support targets that are explicitly compiled for, which are currently:
- macOS 64-bit - Intel (
x86_64-apple-darwin
) - macOS 64-bit - Silicon (
aarch64-apple-darwin
) - Linux 64-bit - GNU (
x86_64-unknown-linux-gnu
) - Linux 64-bit - musl (
x86_64-unknown-linux-musl
) - Windows 64-bit (
x86_64-pc-windows-msvc
)
Initializing moon
Now that we have the CLI installed, let's scaffold and initialize moon in a repository with the
moon init
command. Be sure to access the binary
as mentioned above.
$ moon init
When executed, the following operations will be applied.
- Creates a
.moon
folder with associated.moon/workspace.yml
and.moon/project.yml
configuration files. - Appends necessary ignore patterns to the relative
.gitignore
. - Infers the Node.js version from any
.nvmrc
or.node-version
file. - Infers the package manager based on any existing config and lock files.
- Infers the package manager version from the
packageManager
field inpackage.json
. - Infers projects from the
workspaces
field inpackage.json
. - Infers the version control system from the environment.