# Stack: Node.js The Node-specific rewrites. Read this together with `core/DECISION.md` (which recipe applies and why) and `core/KEELSON_YAML.md` (the config contract). This file is self-contained for Node — you do not need `stacks/python.md` or `stacks/go.md`. Runtimes: `node-slim` (default) / `node-media`. Dependencies come from `package-lock.json` or `package.json`; the build runs `npm ci` (with lockfile) or `npm install`, then `npm run build --if-present`. ## Recipe: bind to `PORT` and `0.0.0.0` The app must listen on the injected `PORT` and bind `0.0.0.0`. A hard-coded port or a `127.0.0.1` / `localhost` bind will not receive traffic. ```js // contract:skip — Node before/after // BEFORE app.listen(3000, "localhost"); // AFTER const server = app.listen(process.env.PORT || 8080, "0.0.0.0"); ``` ## Recipe: graceful shutdown on `SIGTERM` An app that owns its Node HTTP server (Express, Hono's Node adapter, Fastify, or plain `node:http`) must stop accepting new connections on `SIGTERM`, let in-flight requests finish, and exit within Keelson's ten-second termination window. Keep the server returned by `listen()` and install the handler once: ```js // contract:skip — Node HTTP server shutdown let shuttingDown = false; process.on("SIGTERM", () => { if (shuttingDown) return; shuttingDown = true; server.close((error) => { process.exitCode = error ? 1 : 0; }); // Drop idle keep-alive sockets now; active requests continue until complete. server.closeIdleConnections?.(); setTimeout(() => { // Leave one second inside the platform's ten-second SIGKILL deadline. server.closeAllConnections?.(); process.exit(1); }, 9_000).unref(); }); ``` Close database clients and other resources in the `server.close` callback before allowing the process to exit. Use the framework equivalent where it owns the server (`await fastify.close()`, for example), with the same nine-second upper bound. Do not call `process.exit()` immediately in the signal handler: that cuts off in-flight writes. A framework-managed command such as `next start` owns its signal handling; do not wrap it in a second ad-hoc HTTP server. ## Recipe: SQLite file → Keelson Managed SQLite (libSQL) Replace the direct-file SQLite client with a libSQL client that reads `KEELSON_DB_URL` / `KEELSON_DB_AUTH_TOKEN`, and set `db.mode: libsql`. Keep a `file:` URL as the **local-dev fallback** so the app still runs without an injected managed DB. ```yaml # keelson.yaml — fragment. Merge into your file; required fields are in core/KEELSON_YAML.md. db: mode: libsql ``` Replace `better-sqlite3` / `node:sqlite` with `@libsql/client`. ```js // contract:skip — Node before/after // BEFORE import Database from "better-sqlite3"; const db = new Database("app.db"); // AFTER import { createClient } from "@libsql/client"; const db = createClient({ url: process.env.KEELSON_DB_URL ?? "file:local.db", // file: = local fallback authToken: process.env.KEELSON_DB_AUTH_TOKEN, }); await db.execute("CREATE TABLE IF NOT EXISTS items (id INTEGER PRIMARY KEY, note TEXT)"); await db.execute({ sql: "INSERT INTO items (note) VALUES (?)", args: ["hello"] }); ``` Note `@libsql/client` is async (`await`), whereas `better-sqlite3` is synchronous. So the swap also means putting `await` on the calls and making their callers `async`. **That conversion is part of this recipe — do not ask a separate question about it.** Whether the swap as a whole is `auto` or `ask` is decided by the decision table (`core/DECISION.md` → Adaptation Decision Function): `node:sqlite` and Drizzle derive `auto`; raw `better-sqlite3` derives `ask` because its local CRUD is untested in the ledger. The `await` rewrite touches every route handler, but it changes no SQL, no schema, and no behaviour; a confirmation prompt here is noise, and there is no alternative outcome to offer if the user says no. The same holds for Drizzle: swap `better-sqlite3` for `drizzle-orm/libsql` and `await` the queries — the schema and the query expressions are untouched. After rewriting: no `better-sqlite3` import should remain in the data path, and the app must read `KEELSON_DB_URL`. The environment-leak rules that come with holding `KEELSON_DB_AUTH_TOKEN` are in `core/DECISION.md` → SQLite→libSQL. Keep the `?? "file:local.db"` default. It is what lets `node server.js` still start on the user's machine, and `core/DECISION.md` → Local Development Parity makes that a success condition of the adaptation. The wiring lint reports `no-local-dev-path` if it goes missing. ### Moving an existing file's data (there is no path for it) The swap moves the *code*, not the *rows*. The managed database starts **empty**: the app recreates its schema, and the rows already in `app.db` are **not** carried over. Keelson does not ship a data-move step today — an agent can produce a SQL dump of the old file locally (`sqlite3 app.db .dump > dump.sql`), and load it with `keelson db apply dump.sql --app ` (`reference/DB_APPLY.md`: 16 MiB per apply; once the database is non-empty an apply needs the user's approval). If the existing file holds data the user would miss, this is an `ask`, and the proposal must say plainly that existing rows will not come across (`core/DECISION.md` → the existing-data trigger). ## Recipe: Prisma → `@prisma/adapter-libsql` Prisma against a SQLite file (`provider = "sqlite"`) moves to the libSQL driver adapter. This is an `ask` (`core/DECISION.md` → Grading): three things past the connection change, and one of them (migrations) has no clean answer yet. **Pin the adapter to the Prisma Client's major.** Driver adapters went GA in Prisma **6.16.0** (official docs); the version measured working on Keelson is **6.19.3** (deals--claude--01). `npm` will resolve `@prisma/adapter-libsql` 7.x against a 6.x client and break at runtime — pin the adapter to the same major as `@prisma/client`. Prisma 7 changes connection configuration and adapter handling and has **not** been verified here; do not assume the 6.x recipe carries across. ```jsonc // contract:skip — package.json (adapter pinned to the client's major) "dependencies": { "@prisma/client": "6.19.3", "@prisma/adapter-libsql": "6.19.3", "@libsql/client": "^0.14.0" } ``` `@libsql/client` sits alongside the adapter here, as the upstream docs and the measured trial both do — npm resolves the app's `0.14.x` and the adapter's own `0.8.x` at different tree levels without conflict. The version that matters to pin is the **adapter → client major** (`@prisma/adapter-libsql` to `@prisma/client`); `npm` otherwise resolves the adapter at 7.x against a 6.x client and breaks. ```prisma // contract:skip — schema.prisma: keep provider = "sqlite"; the adapter supplies the connection datasource db { provider = "sqlite" } ``` ```js // contract:skip — Prisma Client construction (adapter 6.19.3) import { PrismaClient } from "@prisma/client"; import { PrismaLibSQL } from "@prisma/adapter-libsql"; // PrismaLibSQL takes the libSQL CONFIG object ({ url, authToken }) and builds the // client itself. Do NOT pass a `createClient(...)` instance here — 6.19.3's // constructor reads `.url` off the argument, so a client instance yields // `URL_INVALID: The URL 'undefined'`. const adapter = new PrismaLibSQL({ url: process.env.KEELSON_DB_URL ?? "file:local.db", // file: = local fallback authToken: process.env.KEELSON_DB_AUTH_TOKEN, }); export const prisma = new PrismaClient({ adapter }); ``` - **Externalize the native client** or the bundler build fails. On Next.js set `serverExternalPackages: ["@libsql/client", "@prisma/adapter-libsql"]` in `next.config.js`; on a plain Node build, do not let the bundler inline it. - **Migrations do not run against the managed database.** `prisma migrate deploy` does not work against a remote libSQL database (measured — a reproducible upstream limit, not a trial artefact). Generate migrations locally with `prisma migrate dev`; there is **currently no** supported way to apply them to the managed database at deploy time. For a **single-table, greenfield** schema you may bootstrap it once at startup with idempotent `CREATE TABLE IF NOT EXISTS` DDL (via `$executeRawUnsafe`), kept in sync with `migration.sql` by hand — this is a bootstrap, **not** a migration path, and it does not generalise to schema changes or multiple concurrently-booting instances. Do not build a deploy-time migration path into the app. ## Recipe: File I/O → `files` SDK / `media` SDK Which of the two applies (or whether it belongs in the database) is decided by `core/DECISION.md` → Recipe: local file I/O. This is the Node call shape. Declare each SDK that the app uses as a dependency: run `npm install @keelsonhq/media` for `media` and `npm install @keelsonhq/files` for `files`. If the repository commits `package-lock.json`, commit the updated `package.json` and `package-lock.json` together; the build runs `npm ci`, which fails when those files disagree. If the repository has no lockfile, updating `package.json` is sufficient and the build runs `npm install`. ### `files` — a file the app names and updates (`auto`) Replace `node:fs` calls with `@keelsonhq/files`. The key is the old filename: ```js // contract:skip — Node before/after // BEFORE import fs from "node:fs/promises"; await fs.writeFile("seen_urls.json", JSON.stringify(d)); const seen = JSON.parse(await fs.readFile("seen_urls.json", "utf8").catch(() => "[]")); // AFTER import { write, read } from "@keelsonhq/files"; await write("seen_urls.json", JSON.stringify(d)); const raw = await read("seen_urls.json"); const seen = JSON.parse(raw ? Buffer.from(raw).toString("utf8") : "[]"); ``` `read()` resolves to `null` for a key that was never written — that replaces the `.catch(() => …)` guard, since a first run is the normal path rather than an error. `write()` overwrites and resolves once the write is durable; `del(key)` is idempotent and `list(prefix)` enumerates keys. Both are `async`: **await them.** An un-awaited `write()` is the one way to lose data here (`reference/RPO_CONTRACT.md`). ### `media` — uploads and generated media served by ID (`ask`) `express.static("uploads")` and multer's `diskStorage` are the signals. Store the ID `put()` returns and serve from `/__keelson/media/`; multer moves to `memoryStorage` so the bytes never touch the disk: ```js // contract:skip — Node before/after // BEFORE const upload = multer({ dest: "uploads/" }); app.use("/uploads", express.static("uploads")); app.post("/photos", upload.single("photo"), (req, res) => { db.prepare("INSERT INTO photos (path) VALUES (?)").run(req.file.path); }); // AFTER import { put, url } from "@keelsonhq/media"; const upload = multer({ storage: multer.memoryStorage() }); // no static route app.post("/photos", upload.single("photo"), async (req, res) => { const id = await put(req.file.buffer, { filename: req.file.originalname, contentType: req.file.mimetype, }); await db.execute({ sql: "INSERT INTO photos (media_id) VALUES (?)", args: [id] }); // the page now links url(id) -> /__keelson/media/ }); ``` The new `media_id` column, the dropped `express.static` route, and the changed URL are why this one is `ask` — get the user's approval before doing it. ### Local development parity Both SDKs write real files on the user's machine with no environment set: `files` under `./.keelson/files/`, `media` under `MEDIA_DIR` (default `./media`). `node server.js` keeps working, which `core/DECISION.md` → Local Development Parity requires. Add `.keelson/` and `media/` to `.gitignore`. ## Recipe: add an npm lockfile alongside pnpm / yarn The Node builder only runs npm. `package-lock.json` is honored (`npm ci`); with no lockfile at all the build runs `npm install`. A repository whose only lockfile is `pnpm-lock.yaml` or `yarn.lock` is stopped by `keelson deploy --check` with `lockfile_unsupported` (an error, `ok: false`), so add `package-lock.json` first. The pnpm / yarn lockfiles may remain in the repository alongside it. ```bash # contract:skip — from the project root npm install # generates package-lock.json ``` Commit the resulting `package-lock.json`; do not remove the existing pnpm or yarn lockfile. ## Production Hardening Node apps carry their production/dev split in `NODE_ENV` and in which server command runs. Both must land on the production side here, and neither should require an env var to be *remembered*: **production-safe is the default, local opts INTO dev.** A flag defaulted to dev means a forgotten env var ships stack traces to a public URL. **`NODE_ENV` is not one of the platform's auto-set variables** — the injected set is `PORT` / `TZ` / `KEELSON_*` only (`core/KEELSON_YAML.md` → Auto-set Environment Variables). Nothing sets it for you, and Node defaults to development, so **declare it yourself**: ```yaml # keelson.yaml — fragment. Merge into your file; required fields are in core/KEELSON_YAML.md. env: NODE_ENV: "production" db: mode: libsql ``` This is what Express reads to disable its dev-mode stack-trace error page, what Next.js and most middleware branch on, and what npm uses to skip devDependencies. Leaving it out is the quiet half of this section: the app runs, and every error response carries a stack trace. `NODE_ENV` is the one exception to "local opts INTO dev" here, and it is not a real one: the value is declared in `keelson.yaml`, which only applies on Keelson. Locally the variable is simply unset and Node's own default (development) takes over — the safe value still wins where it matters, and local dev still works. ### Express ```js // contract:skip — production error handling // The default handler prints the stack in dev. Do not send it to the client: // it exposes file paths, dependency versions, and query text. app.use((err, _req, res, _next) => { console.error(err); // logs: yours, via keelson logs app res.status(500).json({ error: "Internal Server Error" }); // response: no stack }); ``` - Do not enable verbose/debug middleware by default (`errorhandler`, a `DEBUG=*` default). If it is env-gated, the default must be off. - Session/JWT secrets come from `secrets`, never a literal (`core/DECISION.md` → hard-coded API keys). - The app sits behind the edge and the gateway, so configure `trust proxy` for that actual proxy path and the forwarded headers before relying on `req.ip` / `req.protocol`. A fixed `app.set("trust proxy", 1)` may not match; verify with a deployed request rather than assuming a hop count. ### Next.js Next must be **built**, and started with `next start` — not `next dev`. The dev server compiles per request, watches the filesystem, and serves unminified sources with full error overlays; it is the single most common Next.js misdeploy. ```yaml # keelson.yaml — complete file. Copy it, then change slug. slug: my-app runtime: node-slim # workspace: acme-corp # uncomment and set your workspace slug if you belong to more than one command: "npm run start" # package.json: "start": "next start -p $PORT" db: mode: none # switch to libsql if the app stores data (see core/DECISION.md) ``` - `"start": "next dev"` in `package.json` must be corrected, not worked around. - Confirm `npm run build` exists and produces `.next/` — `next start` fails without it. - Server-side code reads `KEELSON_DB_URL` at runtime; do not inline it into a `NEXT_PUBLIC_*` variable, which is baked into the client bundle and shipped to every browser. - The native libSQL client must be externalized or the build fails: `serverExternalPackages: ["@libsql/client"]` in `next.config.js`. A **Prisma** app externalizes the adapter too — `["@libsql/client", "@prisma/adapter-libsql"]` (see the Prisma recipe above).