Adopt an existing workspace

You do not need to start a new repository to use Megamono. Adoption helps you understand the projects you already have and choose which conventions to add.

Before you start

#

Check the existing-workspace requirements, including any platform plugins you plan to use.

Use your repository's existing Node version and package manager. Create a branch and commit or set aside unrelated changes so the adoption diff is easy to review. Choose your package manager in the examples below. npm, pnpm, and Bun install the CLI globally; Yarn 2+ runs it with yarn dlx for each command:

npm install -g @megamono/cli

Run the following commands from the workspace root. Adopting Megamono does not require upgrading Nx or TypeScript just to match a new-workspace template.

Explore your repository

#

megamono adopt --survey

The survey lists projects, toolchains, documentation, and existing workflows without applying changes to your repository. It may download tooling if the local plugin is missing, so allow registry access.

Check that the project list looks right. If a project cannot be identified, review the reported configuration or missing dependencies before continuing.

Preview a small first step

#

megamono adopt --profile=pilot --dry-run --interactive=false

The pilot introduces lint, health checks, and project discovery while keeping your existing CI and release workflows. Read the proposed file changes. If Megamono needs a decision about a project or deployment, supply the requested mapping and preview again.

The workspace initialization options describe those mappings and the additional modules you can choose later.

Apply and check

#

Once the preview matches what you want:

megamono adopt --profile=pilot --write --yes --interactive=false
megamono health --profile=development
megamono verify dependencies

Review the Git diff and run your applications' existing tests and builds. Commit the adoption changes separately from any application refactoring so you can review or undo them independently.

Keep going

#

Follow Adopt gradually without weakening checks to review warning budgets, preserve stricter lint rules, and ensure check results are fresh after upgrading. Health reports describe their coverage; a successful report is not a release gate.

Learn about repository structure, add documentation conventions, or connect platform projects. You can introduce these gradually.