# Adopt an existing workspace

Add Megamono to an Nx repository while keeping your applications and workflows.


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](/docs/workflows/requirements#workspace-toolchains), 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:

```sh
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

```sh
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

```sh
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](/docs/generators/workspace-init) describe those mappings and the additional modules you can choose later.

## Apply and check

Once the preview matches what you want:

```sh
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](/docs/workflows/governance) 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](/docs/workflows/repository-structure), add [documentation conventions](/docs/workflows/documentation), or connect [platform projects](/docs/platforms). You can introduce these gradually.