---
name: mongodb-nextjs
description: "Provisions a MongoDB database for a Next.js app with `npx extraorbital add mongodb` (no signup, no card) and wires it into Next.js with `mongodb`. Use when a Next.js project needs MongoDB, Mongo, a document database, MONGODB_URI or Mongoose, or when MONGODB_URI is missing or unset in .env."
---

# MongoDB in Next.js

<!-- Generated from ExtraOrbital's service registry by `pnpm skills:build` in platform/app. Edit the generator, not this file. -->

ExtraOrbital provisions a MongoDB database in one command and writes the credentials into the project's env file. For anything this recipe does not cover, use the `extraorbital` skill or https://extraorbital.dev/llms.txt.

## 1. Provision

```bash
npx extraorbital add mongodb
```

Run it from the project root. It is idempotent (a second run returns the same resource) and writes to `.env.local` if the project has one, otherwise `.env`, keeping that file out of git. Add `--json` to parse the result; credential values are redacted there, and you should never print them either.

| Variable | |
| --- | --- |
| `MONGODB_URI` | Carries the user, the password, TLS and the one database they reach |

Free on the Prototype plan: 512 MB, shared RAM and vCPU.

## 2. Install the client

```bash
npm install mongodb
```

## 3. Connect

Next.js loads both `.env.local` and `.env`, so either file ExtraOrbital writes is read on the next `next dev`.

**`lib/mongodb.ts`**

```ts
import { MongoClient } from "mongodb";

const cached = globalThis as typeof globalThis & { __mongo?: MongoClient };

// One client per process: dev reloads and warm serverless invocations reuse its pool.
export const mongo = (cached.__mongo ??= new MongoClient(process.env.MONGODB_URI!));
// The database named in the connection string: the only one the credentials reach.
export const mongoDb = mongo.db();
```

## 4. Use it

**`app/api/mongodb/route.ts`**

```ts
import { mongoDb } from "@/lib/mongodb";

export async function GET() {
  await mongoDb.collection("events").insertOne({ type: "ping", at: new Date() });
  const events = await mongoDb.collection("events").countDocuments();
  return Response.json({ events });
}
```

## 5. Verify

```bash
npx extraorbital list        # the resource is listed as active
npm run dev
curl http://localhost:3000/api/mongodb
```

A JSON answer means the credentials, the client and the route all work. Delete the route afterwards if the app does not need it.

## Pitfalls

- Call `db()` with no name: the user in `MONGODB_URI` is scoped to the database in the string.
- Create the client once, as here; the driver pools connections and connects lazily on the first command. With Mongoose, `mongoose.connect(MONGODB_URI)` takes the same string.
- The driver needs the Node.js runtime: do not import it from `proxy.ts`/middleware or an edge route.
- Import the module only from server code (route handlers, server components, server actions). Only `NEXT_PUBLIC_*` variables reach the browser, and nothing else should.
- With a `src/` directory the module goes in `src/lib/`; without the `@/*` path alias, import it relatively.
- Restart `next dev` after the env file changes: it is read at startup.
- Exit code 3 means the account is past its free allowance: show the human the link the command printed and wait. Do not retry or work around it.

Docs: https://extraorbital.dev/docs/resources/mongo.md