Everything the CLI does, explained.

Installing modules into your own project is completely public. Anyone can browse the registry and add modules to their project without an account, a token, or signing in anywhere.

A module can declare a Mongo collection (e.g. "users") that overlaps with a collection the host app already owns. Without any special handling, that module creates its own, separate collection with that name - one with no connection to who can actually log into the app.

nextapi sync checks for this at install time. If a module's own model fields are compatible with a collection the host already has, it offers to link the module to the real data instead of creating a duplicate:

'@alice/user-management' declares a "users" collection compatible with the
host's existing UserCollection. Link it instead of creating a separate collection? (y/N)

Confirm and the module's generated code is rewritten to call the host's real collection helper - no second collection, no drift between what the module knows about and what's actually real. Pass --yes to confirm automatically for non-interactive runs.

The decision is remembered. Installing a new version of an already-linked module re-links it automatically - a user isn't asked again every time they update. If a new version's schema stops matching, it falls back to its own collection instead of staying linked to something it no longer fits, and sync warns explicitly: anything the module already wrote through the link stays in the host's real collection, but new writes go to its own collection until it's re-linked.

Matching fields isn't the whole story. A module can also call methods on its collection class (UserCollection.count(...), .list_page(...)) that the host's real UserCollection doesn't have. When that happens, sync copies the module's own implementation of exactly those methods into the host's real models_mongo.py - purely additive, never touching or overwriting a method the host already has, since something else (like /auth/register) may already depend on it behaving exactly as it does today:

Linked '@alice/user-management' to the host's existing UserCollection.
  Adopted into UserCollection: count, list_page
  (these are now part of the host's UserCollection - inspect backend/models_mongo.py)

Field compatibility also can't catch data that predates the field: a users collection may hold documents written before a field existed on the host's model, especially if that model was never enforced on every write path. Sync samples the host's actual MongoDB collection at link time and, if a field the host's model declares required is missing from real, existing documents, asks explicit consent before demoting that field to optional in the host's schema:

'users' collection: 'created_at' is declared required, but missing from
214/1,048 existing documents. Demote 'created_at' to optional in the
host's UserMongo model to match reality? (y/N)

Installing a public module that doesn't link? Fork it - by hand, or by handing the field-mismatch report to the AI Builder and asking it to update the module's model to match - then republish. A module that links correctly once keeps linking for everyone who installs it after that.

Some modules aren't a new page alongside what a project already has - they're a replacement for it. A custom login screen, a different landing page, a redesigned register flow. A route entry can opt into this with overwriteRoute: true:

"frontend": {
  "routes": [
    { "path": "/login", "sourceDir": "frontend/app/login",
      "overwriteRoute": true, "overwriteRouteAck": true }
  ]
}

overwriteRouteAck: true is required alongside it - the registry rejects a publish that sets overwriteRoute without it. It exists so replacing existing content is something a module author had to deliberately confirm in the manifest itself, not something a CLI prompt alone can be scripted past.

The first time anything overwrites a given path on the installing project, its sync warns explicitly and asks to confirm:

'@alice/custom-login' wants to REPLACE your existing content at '/login'. This is
normally irreversible - your current files there will be backed up, but only
restorable via `nextapi rollback /login`, a separate explicit command. Continue? (y/N)

Confirm, and the project's current content at that path is captured first - not just deleted. The capture is a real snapshot: the original files, plus enough bookkeeping that database and backend wiring still work correctly if the route is ever rolled back. Only after that capture succeeds does the new module's content actually replace what was there.

Overwriting a path already occupied by another installed module (rather than the project's original, native content) works the same way: that module is removed first, then the new one takes its place. Rolling back later always restores whatever was captured at the very first overwrite of that path, regardless of how many modules have occupied it since.

This requires MongoDB (DATABASE_TYPE=mongo in backend/.env) on the installing project from the first overwrite onward, same as any other installed module.

Publishing is the one part of this workflow that needs an account. You'll need an access token to prove the CLI is acting on your behalf, it keeps your account secure without asking you to type your password every time.

Every module is described by a single manifest file at its root. Here's a real one:

{
  "id": "ai-notes",
  "version": "1.0.0",
  "nextapiVersion": ">=1.0.0 <2.0.0",
  "displayName": "AI Notes",
  "description": "Adds a protected /notes page...",
  "category": "ai",
  "author": { "name": "NextAPI", "url": "" },
  "license": "MIT",
  "requires": { "modules": ["profile-page@^1.0.0"] },
  "env": {
    "backend": [
      { "key": "ANTHROPIC_API_KEY", "required": true, "secret": true }
    ],
    "frontend": []
  },
  "dependencies": {
    "frontend": { "npm": { "react-markdown": "^9.0.0" } },
    "backend": { "pypi": { "anthropic": "^0.40.0" } }
  },
  "frontend": {
    "routes": [{ "path": "/notes", "protected": true, "label": "Notes" }]
  },
  "backend": {
    "router": { "module": "backend/router.py", "attr": "router", "prefix": "/notes" },
    "collection": "module_ai_notes"
  },
  "functions": {
    "uses": ["auth.get_current_user", "profile.get_display_name"]
  },
  "postInstall": { "message": "Set ANTHROPIC_API_KEY, then run `nextapi sync`." },
  "notes": "A full notes page with AI summarization, not just a text field."
}

* Required.

Nothing stops two different people from wanting to call their module profile-page. To keep every name unique, plain names are reserved for official modules, and everyone else publishes under their own username.

A unique name on its own isn't quite enough, since two people's modules could still both want the page /profile. So when a module is installed, anything that could clash is namespaced automatically:

• Pages: /profile installs at its own unique path. Nobody browses an installed app by typing raw URLs, and the sidebar/nav label always comes from your module's own display name, so there's no reason for an installed route to expose whose module it is
• Server-side code: kept under its own separate namespace per module
• Database storage: kept separate per module too, even if two authors used the same names

You can write your module as if it were the only one that will ever exist. The rest is handled for you when it's installed - even down to two of your own modules that happen to declare the same route.

When you need a specific version of a module, or a module depends on one, you can write it as:

When two modules need different versions

By default, every module keeps exactly one installed version at a time. If two of your installed modules depend on the same module at incompatible majors, nextapi sync resolves compatible-but-different ranges to one shared version automatically, and only surfaces a real conflict - naming both requirements - when a module you rely on genuinely can't satisfy both at once.

A module that would rather support multiple installed majors side by side than force that choice can opt in with "shareable": false. Each dependent then gets wired to whichever version it actually declared, automatically, with no manual resolution needed. This only makes sense for a module with no persisted state of its own - two live copies of something meant to be a single shared source of truth would fork the data, not share it, so a module that owns a backend.collection should leave shareable at its default.

For a module that does own persisted data, the shape of what's already stored is versioned separately from the module itself, via schemaVersion. Bumping it requires publishing a normalizer (functions.provides) that upgrades an older document to the current shape on read, so your code's own version can move forward freely without ever leaving a previously-stored document unreadable.

You don't need a local project to make a module. The /builder page lets anyone with an account write one in the browser and publish it.

The code editor

Files open in a full code editor (the same engine as VS Code), served from this site with no third-party requests. It understands the languages a module is written in:

• TypeScript / JavaScript (.ts .tsx .js .jsx): syntax highlighting, completion and live error checking as you type. Imports from the host app (such as @/components/ui/button) aren't flagged, since the editor can't see them
• Python (.py): highlighting, plus syntax errors marked on the exact line each time you save. A module whose Python doesn't parse can't be published
• JSON (module.json): highlighting and live syntax checking
• Any other file type opens as plain text and is never blocked

Press Ctrl/Cmd + S to save. Saving re-runs the module's checks and shows the result above the editor; Preview renders the page with sample data.

Admins also have the AI Builder at /ai-builder, where Claude writes the module from a description. It's a separate page with its own drafts, and its modules can be opened in the same editor.

A module is public or private, chosen when it's first published. Private modules don't appear in search or Discover, and only you can see them - until you share one.

What someone you share with can do

• View the module's page and preview it
• Install it with the CLI, using their own token: nextapi add @you/module-name
• They can't publish new versions, yank, delete, fork or re-share it - those stay with you

Good to know

• Removing someone stops them installing or viewing it from then on, but doesn't remove copies they already installed - the code is theirs to keep once installed
• You can share a module with up to 100 people
• Visibility is fixed when a module is first published; a public module can't be shared, since anyone can already install it