---
title: "Adopt an existing app"
description: "Bring a Next.js or Node app onto MainSDK one module and one pull request at a time, with its sign-in and checkout locked first."
section: "guides"
status: "Building for 0.5"
spec: "migration-skill"
canonical: "https://mainsdk.dev/docs/guides/adopt-an-existing-app"
updated: "2026-10-28"
---

# Adopt an existing app

> Bring a Next.js or Node app onto MainSDK one module and one pull request at a time, with its sign-in and checkout locked first.

Status: Building for 0.5 · Canonical: https://mainsdk.dev/docs/guides/adopt-an-existing-app · Updated: 2026-10-28

You will scan an app you already have, read the gaps, lock the flows that must keep working and move one module. It takes about 30 minutes for the first module.

## You need

- A Next.js or Node app in a git repository, with a clean working tree.
- Node 22.18 or later.

## 1. Scan and read the report

```bash
npx mainsdk adopt scan
npx mainsdk adopt report
```

`scan` writes a `main.yaml` that describes the app as it is and changes no code. `report` ranks the gaps against the Main 27 baseline: secrets, access, data and the rest. Both run on your machine and send nothing.

## 2. Lock the flows that must keep working

```bash
npx mainsdk adopt lock
```

This records sign-in and checkout as locked flows. Every later module is gated by `mainsdk check` and by those flows, so a change that breaks either does not land.

## 3. Move one module

```bash
npx mainsdk adopt next
```

`adopt next` picks the module with the biggest gap, creates one branch and one commit, and stops. Open the pull request yourself, with your agent or with `gh`. Run `mainsdk adopt` with no step to carry on from where you stopped; it is safe to re-run.

What the app already runs stays. A Clerk sign-in stays `auth.driver: clerk` and an OpenFGA model stays `access.driver: openfga`.

## 4. Finish

```bash
npx mainsdk adopt finish
```

It says the baseline is met, or exactly what remains.

## Check that it works

- `mainsdk check` passes on the branch.
- `.mainsdk/adopt.json` shows the module under `done`.

## Next

- [Adopt: interface reference](https://mainsdk.dev/docs/interfaces/adopt)
- [Start a project](https://mainsdk.dev/docs/guides/start-a-project)