@cloudgrid-io/mcp 0.11.0 → 0.12.0

package/src/corpus/templates/api-service/index.md

@@ -0,0 +1,225 @@
+# Template: api-service (Node HTTP + Mongo REST API)
+
+A minimal but real, deployable backend API. A plain Node `http` server (no web
+UI, no framework) serving a small REST resource (`/items`) backed by the
+grid-shared MongoDB. Data survives refresh and is shared across sessions. This is
+the plain-service sibling of `app-with-data` — use it when the user wants a
+backend/API, not a full web app.
+
+**Key rules (all proven by a real end-to-end deploy):**
+
+1. **Service code MUST live under `services/<name>/`, not the repo/template
+   root.** `path:` in `cloudgrid.yaml` is the URL mount, NOT the filesystem path.
+   The service named `api` → the CLI looks for `services/api/`. Files at the root
+   fail with `Error: Service directory not found: …/services/api`.
+2. **Read the DB connection string LAZILY (inside the getter), never at module
+   top level.** The grid injects it as the `DATABASE_MONGODB_URL` environment
+   variable (plus the legacy `MONGODB_URL` alias) at dev-time and runtime; the
+   service reads `process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL`
+   inside `getClient`. A top-level `const uri = process.env.DATABASE_MONGODB_URL;
+   if (!uri) throw` crashes node startup before the grid injects the var. Never
+   hardcode a connection string; never commit a secret.
+3. **Declare the datastore with `needs: { database: true }`.** This is the
+   canonical shape — the deployer provisions Mongo and injects
+   `DATABASE_MONGODB_URL` (plus the legacy `MONGODB_URL` alias). `requires:` is
+   the deprecated v1 alias; don't author new yaml with it, and never set `needs:`
+   and `requires:` together (the validator rejects the combination).
+4. **Listen on `process.env.PORT || 8080`.** The grid injects `PORT`; the `8080`
+   default is for local runs.
+
+Write these files into the scaffolded app folder — the service code goes under
+`services/api/` — adapt the resource/fields to the user's API, then `grid dev`
+(local) / `grid plug` (deploy, async — poll to a live URL).
+
+## File tree
+
+```
+cloudgrid.yaml                 # name + services.api (node) + needs: { database: true }
+services/api/package.json      # type: module, main src/index.js, mongodb driver only
+services/api/src/index.js      # Node http server on PORT||8080; /items GET/POST/DELETE on Mongo
+```
+
+## cloudgrid.yaml
+
+```yaml
+# Rename this service. The grid injects the DB connection string as an
+# environment variable at runtime — do NOT set it yourself, and never commit a
+# connection string or secret.
+#
+# `needs: { database: true }` is the canonical, recommended shape. The deployer
+# provisions Mongo and injects DATABASE_MONGODB_URL (plus the legacy MONGODB_URL
+# alias). `requires:` is the deprecated v1 alias — don't author new yaml with it,
+# and never set `needs:` and `requires:` together (the validator rejects it).
+#
+# This is a plain Node HTTP service (type: node), not a web UI. Service code lives
+# under services/api/ — `path:` is the URL mount, not the filesystem path.
+name: my-api
+services:
+  api:
+    type: node
+    path: /
+needs:
+  database: true
+```
+
+> **Capability:** this template's need is `database: true`. The deployer
+> provisions Mongo and injects `DATABASE_MONGODB_URL` (plus the legacy
+> `MONGODB_URL` alias), so a service reading either var works. `requires:` is the
+> deprecated v1 alias — don't mix it with `needs:` (the validator rejects the
+> combination). See the capability-map for the full injection table.
+
+## services/api/package.json
+
+```json
+{
+  "name": "api",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/index.js",
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "dependencies": {
+    "mongodb": "^6.12.0"
+  }
+}
+```
+
+## services/api/src/index.js
+
+```js
+// A minimal REST/JSON API backed by grid-shared Mongo.
+//
+// Endpoints (resource: `items`):
+//   GET    /items      -> list items (newest first)
+//   POST   /items      -> create an item; body { "text": string }
+//   DELETE /items?id=…  -> remove an item by id
+//   GET    /           -> tiny service banner + endpoint list
+//
+// The grid injects DATABASE_MONGODB_URL (plus the legacy MONGODB_URL alias) at
+// dev + runtime. The env var and Mongo client are resolved LAZILY (inside
+// getClient), never at module top level — a top-level read throws at node
+// startup, before the grid injects the var, and crashes the service. Never
+// hardcode a connection string; never commit a secret.
+import { createServer } from "node:http";
+import { MongoClient, ObjectId } from "mongodb";
+
+let clientPromise;
+
+function getClient() {
+  const uri = process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL;
+  if (!uri) {
+    throw new Error(
+      "DATABASE_MONGODB_URL is not set. The grid injects it automatically — run " +
+        "this service with `grid dev` locally, or deploy it with `grid plug`. Do " +
+        "not set it by hand.",
+    );
+  }
+  if (!clientPromise) clientPromise = new MongoClient(uri).connect();
+  return clientPromise;
+}
+
+async function items() {
+  const client = await getClient();
+  return client.db().collection("items");
+}
+
+function sendJson(res, status, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, {
+    "content-type": "application/json",
+    "content-length": Buffer.byteLength(payload),
+  });
+  res.end(payload);
+}
+
+function readBody(req) {
+  return new Promise((resolve) => {
+    let data = "";
+    req.on("data", (chunk) => {
+      data += chunk;
+      if (data.length > 1_000_000) req.destroy();
+    });
+    req.on("end", () => {
+      try {
+        resolve(data ? JSON.parse(data) : {});
+      } catch {
+        resolve(null);
+      }
+    });
+    req.on("error", () => resolve(null));
+  });
+}
+
+async function handle(req, res) {
+  const url = new URL(req.url, "http://localhost");
+  const { pathname } = url;
+
+  if (pathname === "/" && req.method === "GET") {
+    return sendJson(res, 200, {
+      service: "my-api",
+      endpoints: ["GET /items", "POST /items", "DELETE /items?id=<id>"],
+    });
+  }
+
+  if (pathname === "/items") {
+    const col = await items();
+
+    if (req.method === "GET") {
+      const list = await col.find({}).sort({ createdAt: -1 }).toArray();
+      return sendJson(
+        res,
+        200,
+        list.map((it) => ({ id: it._id.toString(), text: it.text, createdAt: it.createdAt })),
+      );
+    }
+
+    if (req.method === "POST") {
+      const body = await readBody(req);
+      if (body === null) return sendJson(res, 400, { error: "invalid JSON body" });
+      const text = typeof body.text === "string" ? body.text.trim() : "";
+      if (!text) return sendJson(res, 400, { error: "text is required" });
+      const doc = { text, createdAt: new Date() };
+      const { insertedId } = await col.insertOne(doc);
+      return sendJson(res, 201, { id: insertedId.toString(), ...doc });
+    }
+
+    if (req.method === "DELETE") {
+      const id = url.searchParams.get("id");
+      if (!id || !ObjectId.isValid(id)) {
+        return sendJson(res, 400, { error: "a valid id query param is required" });
+      }
+      const { deletedCount } = await col.deleteOne({ _id: new ObjectId(id) });
+      if (deletedCount === 0) return sendJson(res, 404, { error: "item not found" });
+      return sendJson(res, 200, { ok: true });
+    }
+
+    return sendJson(res, 405, { error: "method not allowed" });
+  }
+
+  return sendJson(res, 404, { error: "not found" });
+}
+
+const server = createServer((req, res) => {
+  handle(req, res).catch((err) => {
+    console.error(err);
+    if (!res.headersSent) sendJson(res, 500, { error: "internal server error" });
+  });
+});
+
+const port = process.env.PORT || 8080;
+server.listen(port, () => {
+  console.log(`api-service listening on :${port}`);
+});
+```
+
+## Adapt it
+
+- Rename the `items` collection in `services/api/src/index.js` to your resource
+  (`notes`, `orders`, `events`).
+- Change the document fields; add validation, owners, timestamps, statuses.
+- Add more routes/resources as the API grows.
+- Return clear JSON errors (`{ "error": … }`) with the right status codes.
+- Add more `needs:` (e.g. `cache: true`) only if you actually use them.
+- Run `grid dev` to test locally, `grid plug` to deploy (async — poll to live).

package/src/corpus/templates/api-service/services/api/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "api",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/index.js",
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "dependencies": {
+    "mongodb": "^6.12.0"
+  }
+}

package/src/corpus/templates/api-service/services/api/src/index.js

@@ -0,0 +1,132 @@
+// A minimal REST/JSON API backed by grid-shared Mongo.
+//
+// Endpoints (resource: `items`):
+//   GET    /items      -> list items (newest first)
+//   POST   /items      -> create an item; body { "text": string }
+//   DELETE /items?id=…  -> remove an item by id
+//   GET    /           -> tiny service banner + endpoint list
+//
+// The grid injects the connection string as the DATABASE_MONGODB_URL environment
+// variable (plus the legacy MONGODB_URL alias) at dev-time (`grid dev`) and
+// runtime (after `grid plug`). Read the canonical var first, fall back to the
+// legacy alias.
+//
+// The env var and Mongo client are resolved LAZILY (inside getDb), never at
+// module top level — a top-level read throws at node startup, before the grid
+// has injected the var, and crashes the service. Never hardcode a connection
+// string here and never commit a secret.
+import { createServer } from "node:http";
+import { MongoClient, ObjectId } from "mongodb";
+
+let clientPromise;
+
+function getClient() {
+  const uri = process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL;
+  if (!uri) {
+    throw new Error(
+      "DATABASE_MONGODB_URL is not set. The grid injects it automatically — run " +
+        "this service with `grid dev` locally, or deploy it with `grid plug` (the " +
+        "grid injects the DB connection string at runtime). Do not set it by hand.",
+    );
+  }
+  if (!clientPromise) clientPromise = new MongoClient(uri).connect();
+  return clientPromise;
+}
+
+async function items() {
+  const client = await getClient();
+  // The default DB comes from the connection-string path segment the grid injects.
+  return client.db().collection("items");
+}
+
+// ── Small JSON helpers ───────────────────────────────────────────────────────
+function sendJson(res, status, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, {
+    "content-type": "application/json",
+    "content-length": Buffer.byteLength(payload),
+  });
+  res.end(payload);
+}
+
+function readBody(req) {
+  return new Promise((resolve) => {
+    let data = "";
+    req.on("data", (chunk) => {
+      data += chunk;
+      if (data.length > 1_000_000) req.destroy(); // basic guard
+    });
+    req.on("end", () => {
+      try {
+        resolve(data ? JSON.parse(data) : {});
+      } catch {
+        resolve(null); // signal invalid JSON
+      }
+    });
+    req.on("error", () => resolve(null));
+  });
+}
+
+// ── Router ───────────────────────────────────────────────────────────────────
+async function handle(req, res) {
+  const url = new URL(req.url, "http://localhost");
+  const { pathname } = url;
+
+  if (pathname === "/" && req.method === "GET") {
+    return sendJson(res, 200, {
+      service: "my-api",
+      endpoints: ["GET /items", "POST /items", "DELETE /items?id=<id>"],
+    });
+  }
+
+  if (pathname === "/items") {
+    const col = await items();
+
+    if (req.method === "GET") {
+      const list = await col.find({}).sort({ createdAt: -1 }).toArray();
+      return sendJson(
+        res,
+        200,
+        list.map((it) => ({ id: it._id.toString(), text: it.text, createdAt: it.createdAt })),
+      );
+    }
+
+    if (req.method === "POST") {
+      const body = await readBody(req);
+      if (body === null) return sendJson(res, 400, { error: "invalid JSON body" });
+      const text = typeof body.text === "string" ? body.text.trim() : "";
+      if (!text) return sendJson(res, 400, { error: "text is required" });
+      const doc = { text, createdAt: new Date() };
+      const { insertedId } = await col.insertOne(doc);
+      return sendJson(res, 201, { id: insertedId.toString(), ...doc });
+    }
+
+    if (req.method === "DELETE") {
+      const id = url.searchParams.get("id");
+      if (!id || !ObjectId.isValid(id)) {
+        return sendJson(res, 400, { error: "a valid id query param is required" });
+      }
+      const { deletedCount } = await col.deleteOne({ _id: new ObjectId(id) });
+      if (deletedCount === 0) return sendJson(res, 404, { error: "item not found" });
+      return sendJson(res, 200, { ok: true });
+    }
+
+    return sendJson(res, 405, { error: "method not allowed" });
+  }
+
+  return sendJson(res, 404, { error: "not found" });
+}
+
+const server = createServer((req, res) => {
+  handle(req, res).catch((err) => {
+    // Never leak internals or a connection string in the response.
+    console.error(err);
+    if (!res.headersSent) sendJson(res, 500, { error: "internal server error" });
+  });
+});
+
+// The grid injects PORT; default to 8080 for local runs.
+const port = process.env.PORT || 8080;
+server.listen(port, () => {
+  console.log(`api-service listening on :${port}`);
+});

package/src/corpus/templates/app-with-data/README.md

@@ -7,23 +7,26 @@ page whose state is in memory only.
 ## How the grid gives you a database
 
 You do **not** provision a database or set a connection string. In
-`cloudgrid.yaml` you declare `requires: [mongodb]`, and the grid:
+`cloudgrid.yaml` you declare `needs: { database: true }`, and the grid:
 
 - provisions shared Mongo for the app, and
-- injects the connection string as the **`MONGODB_URL`** environment variable —
-  at dev-time (`grid dev`) and at runtime (after `grid plug`).
-
-The app reads it via `process.env.MONGODB_URL` in `services/web/lib/db.js` —
-**lazily, inside the `getDb` getter, never at module top level** (a top-level
-read fails `next build`, which imports the module for route analysis before the
-grid injects the var). Never hardcode a connection string; never commit a
-secret. (If you also declare `redis: private`, the grid injects `REDIS_URL` the
-same way.)
-
-> **Use `requires:` (NOT `needs:`).** The CLI warns `requires:` is deprecated,
-> but the deployer currently only injects `MONGODB_URL` from `requires:` —
-> migrating to `needs:` builds fine but injects NO DB connection (every request
-> 500s). Keep `requires:` until CloudGrid's deployer honors `needs:`.
+- injects the connection string as the **`DATABASE_MONGODB_URL`** environment
+  variable (plus the legacy `MONGODB_URL` alias) — at dev-time (`grid dev`) and
+  at runtime (after `grid plug`).
+
+The app reads it via `process.env.DATABASE_MONGODB_URL` (with a legacy
+`process.env.MONGODB_URL` fallback) in `services/web/lib/db.js` — **lazily,
+inside the `getDb` getter, never at module top level** (a top-level read fails
+`next build`, which imports the module for route analysis before the grid injects
+the var). Never hardcode a connection string; never commit a secret. (If you also
+declare `cache: true`, the grid injects `CACHE_REDIS_URL` — and the legacy
+`REDIS_URL` alias — the same way.)
+
+> **Declare `needs: { database: true }` (the canonical shape).** The deployer
+> provisions Mongo and injects `DATABASE_MONGODB_URL` (plus the legacy
+> `MONGODB_URL` alias). `requires:` is the deprecated v1 alias — don't author new
+> yaml with it, and never set `needs:` and `requires:` together (the validator
+> rejects the combination).
 
 ## Service layout
 
@@ -36,7 +39,7 @@ App code lives under **`services/web/`**, not the template root. `path:` in
 
 ```bash
 npm install
-grid dev          # runs Next.js with MONGODB_URL injected against dev Mongo
+grid dev          # runs Next.js with DATABASE_MONGODB_URL injected against dev Mongo
 ```
 
 ## Deploy
@@ -52,9 +55,9 @@ to update the same URL.
 ## File tree
 
 ```
-cloudgrid.yaml                        # name + services.web (nextjs) + requires: [mongodb]
+cloudgrid.yaml                        # name + services.web (nextjs) + needs: { database: true }
 services/web/package.json             # next, react, react-dom, mongodb driver only
-services/web/lib/db.js                # lazy Mongo client from process.env.MONGODB_URL
+services/web/lib/db.js                # lazy Mongo client from DATABASE_MONGODB_URL (legacy MONGODB_URL fallback)
 services/web/app/layout.js            # root layout + inline CSS
 services/web/app/page.js              # server component: reads todos from Mongo
 services/web/app/todo-form.js         # client form: POST/DELETE via the API
@@ -67,4 +70,4 @@ services/web/app/api/todos/route.js   # GET (list) / POST (add) / DELETE (remove
   `services/web/app/page.js` (e.g. `submissions`, `tasks`, `entries`).
 - Change the document fields (add owners, timestamps, statuses).
 - Add more routes/collections as the app grows.
-- Add `redis: private` to `requires` only if you actually need Redis.
+- Add `cache: true` to `needs:` only if you actually need Redis.

package/src/corpus/templates/app-with-data/cloudgrid.yaml

@@ -1,19 +1,15 @@
-# Rename this app. The grid injects MONGODB_URL (and REDIS_URL if you add a cache)
-# as environment variables at runtime — do NOT set them yourself, and never commit
-# a connection string or secret.
+# Rename this app. The grid injects the DB connection string (and a Redis URL if
+# you add a cache) as environment variables at runtime — do NOT set them
+# yourself, and never commit a connection string or secret.
 #
-# NOTE: use `requires:` (NOT `needs:`). The CLI warns that `requires:` is deprecated,
-# but the deployer currently only injects MONGODB_URL from `requires:` — migrating to
-# `needs:` builds fine but injects NO database connection (every request 500s).
-# Keep `requires:` until CloudGrid's deployer honors `needs:`.
+# `needs: { database: true }` is the canonical, recommended shape. The deployer
+# provisions Mongo and injects DATABASE_MONGODB_URL (plus the legacy MONGODB_URL
+# alias). `requires:` is the deprecated v1 alias — don't author new yaml with it,
+# and never set `needs:` and `requires:` together (the validator rejects it).
 name: my-app
 services:
   web:
     type: nextjs
     path: /
-# Canonical capability (metadata): this app needs a database.
-# When #1527 lands (deployer honors needs:), replace requires: with:
-#   needs:
-#     database: true
-requires:
-  - mongodb
+needs:
+  database: true

package/src/corpus/templates/app-with-data/index.md

@@ -9,17 +9,19 @@ so it survives refresh and is shared across sessions — unlike a static page.
    root.** `path:` in `cloudgrid.yaml` is the URL mount, NOT the filesystem path.
    The service named `web` → the CLI looks for `services/web/`. App files at the
    root fail with `Error: Service directory not found: …/services/web`.
-2. **Read `MONGODB_URL` LAZILY (inside the getter), never at module top level.**
-   The grid injects the DB connection string as the `MONGODB_URL` environment
-   variable at dev-time and runtime; the app reads `process.env.MONGODB_URL`
-   inside `getDb`. A top-level `const uri = process.env.MONGODB_URL; if (!uri)
+2. **Read the DB connection string LAZILY (inside the getter), never at module
+   top level.** The grid injects it as the `DATABASE_MONGODB_URL` environment
+   variable (plus the legacy `MONGODB_URL` alias) at dev-time and runtime; the
+   app reads `process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL` inside
+   `getDb`. A top-level `const uri = process.env.DATABASE_MONGODB_URL; if (!uri)
    throw` fails `next build` (the module is imported for route analysis before
    the grid injects the var). Never hardcode a connection string; never commit a
    secret.
-3. **Declare the datastore with `requires: [mongodb]` — NOT `needs:`.** The CLI
-   warns `requires:` is deprecated, but the deployer only injects `MONGODB_URL`
-   from `requires:`; `needs:` builds fine but injects NO DB connection (every
-   request 500s). Keep `requires:` until the deployer honors `needs:`.
+3. **Declare the datastore with `needs: { database: true }`.** This is the
+   canonical shape — the deployer provisions Mongo and injects
+   `DATABASE_MONGODB_URL` (plus the legacy `MONGODB_URL` alias). `requires:` is
+   the deprecated v1 alias; don't author new yaml with it, and never set `needs:`
+   and `requires:` together (the validator rejects the combination).
 
 Write these files into the scaffolded app folder — the app code goes under
 `services/web/` — adapt the collection/fields to the user's app, then `grid dev`
@@ -28,9 +30,9 @@ Write these files into the scaffolded app folder — the app code goes under
 ## File tree
 
 ```
-cloudgrid.yaml                          # name + services.web (nextjs) + requires: [mongodb]
+cloudgrid.yaml                          # name + services.web (nextjs) + needs: { database: true }
 services/web/package.json               # next, react, react-dom, mongodb driver only
-services/web/lib/db.js                  # lazy Mongo client from process.env.MONGODB_URL
+services/web/lib/db.js                  # lazy Mongo client from DATABASE_MONGODB_URL (legacy MONGODB_URL fallback)
 services/web/app/layout.js              # root layout + inline CSS
 services/web/app/page.js                # server component: reads todos from Mongo
 services/web/app/todo-form.js           # client form: POST/DELETE via the API
@@ -40,32 +42,28 @@ services/web/app/api/todos/route.js     # GET (list) / POST (add) / DELETE (remo
 ## cloudgrid.yaml
 
 ```yaml
-# Rename this app. The grid injects MONGODB_URL (and REDIS_URL if you add a cache)
-# as environment variables at runtime — do NOT set them yourself, and never commit
-# a connection string or secret.
+# Rename this app. The grid injects the DB connection string (and a Redis URL if
+# you add a cache) as environment variables at runtime — do NOT set them
+# yourself, and never commit a connection string or secret.
 #
-# NOTE: use `requires:` (NOT `needs:`). The CLI warns that `requires:` is deprecated,
-# but the deployer currently only injects MONGODB_URL from `requires:` — migrating to
-# `needs:` builds fine but injects NO database connection (every request 500s).
-# Keep `requires:` until CloudGrid's deployer honors `needs:`.
+# `needs: { database: true }` is the canonical, recommended shape. The deployer
+# provisions Mongo and injects DATABASE_MONGODB_URL (plus the legacy MONGODB_URL
+# alias). `requires:` is the deprecated v1 alias — don't author new yaml with it,
+# and never set `needs:` and `requires:` together (the validator rejects it).
 name: my-app
 services:
   web:
     type: nextjs
     path: /
-# Canonical capability (metadata): this app needs a database.
-# When #1527 lands (deployer honors needs:), replace requires: with:
-#   needs:
-#     database: true
-requires:
-  - mongodb
+needs:
+  database: true
 ```
 
-> **Capability:** this template's canonical need is `database: true` (see the
-> commented block above and the capability-map). The deployed yaml keeps
-> `requires: [mongodb]` because only `requires:` injects `MONGODB_URL` today
-> (#1527); `needs:` and `requires:` cannot co-exist active in the same yaml, so
-> the canonical `needs:` is shown only as a comment until the deployer honors it.
+> **Capability:** this template's need is `database: true`. The deployer
+> provisions Mongo and injects `DATABASE_MONGODB_URL` (plus the legacy
+> `MONGODB_URL` alias), so an app reading either var works. `requires:` is the
+> deprecated v1 alias — don't mix it with `needs:` (the validator rejects the
+> combination). See the capability-map for the full injection table.
 
 ## services/web/package.json
 
@@ -93,22 +91,23 @@ requires:
 ```js
 // Cached MongoDB client for the App Router.
 //
-// The grid injects the connection string as the MONGODB_URL environment variable
-// at runtime (after `grid plug`) and under `grid dev` locally. Never hardcode a
-// connection string here and never commit a secret.
+// The grid injects the connection string as the DATABASE_MONGODB_URL environment
+// variable (plus the legacy MONGODB_URL alias) at runtime (after `grid plug`) and
+// under `grid dev` locally. Read the canonical var first, fall back to the legacy
+// alias. Never hardcode a connection string here and never commit a secret.
 //
 // The env var and client are resolved LAZILY (inside getDb), never at module top
 // level — otherwise `next build` throws when it imports this module for route
-// analysis, before the grid injects MONGODB_URL.
+// analysis, before the grid injects the var.
 import { MongoClient } from "mongodb";
 
 function clientPromise() {
-  const uri = process.env.MONGODB_URL;
+  const uri = process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL;
   if (!uri) {
     throw new Error(
-      "MONGODB_URL is not set. The grid injects it automatically — run this app " +
-        "with `grid dev` locally, or deploy it with `grid plug` (the grid injects " +
-        "MONGODB_URL at runtime). Do not set it by hand.",
+      "DATABASE_MONGODB_URL is not set. The grid injects it automatically — run " +
+        "this app with `grid dev` locally, or deploy it with `grid plug` (the grid " +
+        "injects the DB connection string at runtime). Do not set it by hand.",
     );
   }
   if (!globalThis.__mongoClientPromise) {
@@ -119,7 +118,7 @@ function clientPromise() {
 
 export async function getDb() {
   const client = await clientPromise();
-  // The default DB comes from the MONGODB_URL path segment the grid injects.
+  // The default DB comes from the connection-string path segment the grid injects.
   return client.db();
 }
 ```
@@ -267,5 +266,5 @@ export async function DELETE(request) {
 
 - Rename the `todos` collection to your data (`submissions`, `tasks`, `entries`).
 - Change the document fields; add owners/timestamps/statuses.
-- Add `redis: private` to `requires` only if you actually need Redis.
+- Add `cache: true` to `needs:` only if you actually need Redis.
 - Run `grid dev` to test locally, `grid plug` to deploy (async — poll to live).

package/src/corpus/templates/app-with-data/services/web/lib/db.js

@@ -1,21 +1,22 @@
 // Cached MongoDB client for the App Router.
 //
-// The grid injects the connection string as the MONGODB_URL environment variable
-// at runtime (after `grid plug`) and under `grid dev` locally. Never hardcode a
-// connection string here and never commit a secret.
+// The grid injects the connection string as the DATABASE_MONGODB_URL environment
+// variable (plus the legacy MONGODB_URL alias) at dev-time (`grid dev`) and
+// runtime (after `grid plug`). Read the canonical var first, fall back to the
+// legacy alias. Never hardcode a connection string here and never commit a secret.
 //
 // The env var and client are resolved LAZILY (inside getDb), never at module top
 // level — otherwise `next build` throws when it imports this module for route
-// analysis, before the grid injects MONGODB_URL.
+// analysis, before the grid injects the var.
 import { MongoClient } from "mongodb";
 
 function clientPromise() {
-  const uri = process.env.MONGODB_URL;
+  const uri = process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL;
   if (!uri) {
     throw new Error(
-      "MONGODB_URL is not set. The grid injects it automatically — run this app " +
-        "with `grid dev` locally, or deploy it with `grid plug` (the grid injects " +
-        "MONGODB_URL at runtime). Do not set it by hand.",
+      "DATABASE_MONGODB_URL is not set. The grid injects it automatically — run " +
+        "this app with `grid dev` locally, or deploy it with `grid plug` (the grid " +
+        "injects the DB connection string at runtime). Do not set it by hand.",
     );
   }
   if (!globalThis.__mongoClientPromise) {
@@ -26,6 +27,6 @@ function clientPromise() {
 
 export async function getDb() {
   const client = await clientPromise();
-  // The default DB comes from the MONGODB_URL path segment the grid injects.
+  // The default DB comes from the connection-string path segment the grid injects.
   return client.db();
 }