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 Status is where the work is: Planned (in a milestone, not started), Building (tickets in progress), Preview (usable, may change), then the stability it ships at.
Stability The promise an interface ships with.
- Stable Follows semantic versioning; breaking changes need a new major, 12 months of overlap and a codemod.
- Beta Usable in production; may change before it becomes stable.
- Experimental May change or go away; needs an explicit opt-in in main.yaml.
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
npx mainsdk adopt scan
npx mainsdk adopt reportscan 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
npx mainsdk adopt lockThis 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
npx mainsdk adopt nextadopt 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
npx mainsdk adopt finishIt says the baseline is met, or exactly what remains.
Check that it works
mainsdk checkpasses on the branch..mainsdk/adopt.jsonshows the module underdone.
Next
Was this page helpful?