Node.js + Express + MongoDB

Curated rule SaaS / Web App · AI / LLM App · Collaboration & Productivity Updated Sep 2026 Which file does my tool read?

node-express-mongodb.md

Production guidelines for Express REST APIs, Mongoose schema design, and MongoDB indexing/transaction discipline.

Node.js Express MongoDB TypeScript Redis

Formats: 4 files
AGENTS.md: 37 lines
CLAUDE.md: 15 lines
Languages: TypeScript
Updated: Sep 2026
Used by: 4 projects

Install

Writes .claude/skills/node-express-mongodb/SKILL.md

$ curl -s --create-dirs -o .claude/skills/node-express-mongodb/SKILL.md https://stackitfast.com/rules/node-express-mongodb/SKILL.md

Rule files

AGENTS.md· 37 lines · 3.6 KB

1	# Project Architecture & Guidelines (Node.js + Express + MongoDB)
2
3	## 1. System Architecture
4	- Runtime: Node.js (TypeScript, `ts-node`/`tsx` for dev, compiled output for production).
5	- Web Framework: Express 4/5 for REST API routing and middleware.
6	- Database: MongoDB with Mongoose for schema definition, validation, and typed models.
7	- Caching/Queues: Redis for session storage, caching, and BullMQ-backed background jobs.
8
9	## 2. Mongoose Schema & Validation
10	- Define explicit schemas with Mongoose (`new Schema({...}, { timestamps: true })`) even though MongoDB is schemaless at the database level — untyped documents are the single largest source of bugs in Node/Mongo codebases.
11	- Use Mongoose's built-in validators (`required`, `enum`, custom `validate` functions) as the first line of defense; add a Zod schema at the API boundary for request-shape validation before it reaches Mongoose.
12	- Prefer embedding for data that's always read together and rarely grows unbounded (a project's settings object); reference (`ObjectId` + `ref`) for data that's queried independently or grows without bound (a project's activity log).
13
14	## 3. Indexing & Query Discipline
15	- Every field used in a `find()` filter, sort, or unique constraint needs an explicit index (`schema.index({ projectId: 1, createdAt: -1 })`) — MongoDB does not warn about missing indexes, it just degrades to a full collection scan.
16	- Use `.lean()` on read-only queries that don't need Mongoose document methods; it skips hydration overhead and meaningfully reduces memory/CPU on hot read paths.
17	- Avoid unbounded `.find({})` without pagination (`.limit()`/`.skip()` or cursor-based pagination) on any collection that can grow past a few thousand documents.
18
19	## 4. Transactions & Data Consistency
20	- Use MongoDB multi-document transactions (`session.startTransaction()`) for any write that spans more than one collection and must be atomic (e.g. deducting credits and creating a record) — MongoDB supports ACID transactions on replica sets, this isn't a "NoSQL means no transactions" situation.
21	- Transactions require a replica set (even a single-node one in development); configure this explicitly rather than discovering it's missing when a transaction call throws in production.
22
23	## 5. Common Pitfalls / Coding Standards
24	- ❌ Querying without an index on a collection expected to grow — profile with `.explain('executionStats')` before shipping a new query pattern.
25	- ❌ Deeply nested embedded arrays that grow unbounded (MongoDB documents have a 16MB size limit).
26	- ✅ Use `.lean()` for read-heavy endpoints; reserve hydrated Mongoose documents for paths that call instance methods or need change tracking.
27
28	## 6. Testing Conventions
29	- Vitest/Jest with `mongodb-memory-server` for fast, isolated integration tests against a real (in-memory) MongoDB instance rather than mocking Mongoose.
30	- Supertest for Express route-level tests, asserting status codes and response shape.
31	- Test index usage explicitly for any query on a collection expected to scale, via `.explain()` assertions in CI if query performance regressions have happened before.
32
33	## 7. Git Workflow & PR Conventions
34	- Conventional Commits scoped to the resource, e.g. `perf(projects): add compound index for owner+status filter`.
35	- New indexes ship in the same PR as the query pattern that needs them, with a migration/init script that creates them idempotently (`createIndexes` is safe to re-run).
36	- Require `tsc --noEmit` and the test suite green before merge.
37	- Squash-merge; run index creation as an explicit deploy step on large collections (it can lock or slow the collection during build).

Works with Cursor · Claude Code · Windsurf · AGY

Architecture notes

Architecture Overview

Standardized production guidelines for Node.js, Express, and MongoDB via Mongoose — the default choice when a project’s data is naturally document-shaped (chat messages, notification payloads, flexible per-tenant configuration) rather than relational.

Verified Real-World Adoption

LibreChat (multi-model AI chat workspace) and Novu (notification infrastructure) both run Node.js/TypeScript + MongoDB in production, and Rocket.Chat uses the same combination for its real-time team communications platform.

Key Architectural Nuances

Schemas Matter Even on a Schemaless Database: Mongoose schemas plus a Zod boundary layer are what actually prevent the “any shape of document can end up in this collection” failure mode that gives MongoDB its reputation for bugs.
Indexes Are Opt-In, Not Automatic: Unlike a well-tuned PostgreSQL setup that at least logs slow queries, MongoDB will silently full-scan an unindexed filter forever — index discipline has to be deliberate, not reactive.

Frequently asked questions

Does this AGENTS.md work with Cursor, Claude Code, and Windsurf?

Yes — AGENTS.md is the open, cross-tool standard read by Cursor, Claude Code, Windsurf, and 30+ other agents. A dedicated .mdc file is also included for Cursor's native .cursor/rules format.

Does MongoDB actually support transactions?

Yes, since MongoDB 4.0, multi-document ACID transactions are supported on replica sets (including a single-node replica set in development). The common misconception that MongoDB can't do transactions dates to pre-4.0 versions; as of any current deployment, if an operation needs to atomically touch more than one document or collection, a session-based transaction is the correct tool, not application-level compensating logic.

When should a field be embedded versus referenced with an ObjectId?

Embed when the data is always fetched together with its parent and has a bounded size (a user's address, a project's settings). Reference when the data is queried independently of its parent, grows without a practical bound (comments, activity logs), or is shared across multiple parent documents. Getting this wrong in the embed direction is how documents hit the 16MB size limit.

Used in production

Explore all stacks

Orca

Agentic Development Environment for Parallel Coding Agents · 6-20 people

Agent CLIs stay the user's own. Orca adds the orchestration layer around them: isolated git worktrees, a PTY daemon that outlives the UI, and a relay for mobile steering. It can support new agents without bundling them.

Fast Jev Compaction

Claude Code Plugin · Solo

Two Jev Noul questions per tool call, gated by a threshold in code, prune a transcript without rewriting it, and a thin hook adapter falls back to Claude Code's built-in summary whenever Jev fails or saves too little.

Open Code Review

Hybrid Deterministic + LLM Agent Code Review Tool · 20+ people

A single static Go binary keeps the review engine fast and easy to distribute through npm, CI and IDE plugins. Putting deterministic diff/context analysis before a narrow LLM loop keeps reviews precise and cheap in tokens compared with general-purpose agents.

Rocket.Chat

Open-Source Team Communications & WebRTC · 20+ people

Combining full on-premises MongoDB ownership with real-time WebSockets gives enterprise organizations secure, private communication without third-party surveillance.

Every stack ships as files

More AI agent coding rules and skills

View all

django-postgres-redis/AGENTS.mdDjango + PostgreSQL + Redis + CeleryDjango · Python · PostgreSQL fastapi-jev-decision-service/AGENTS.mdFastAPI + Jev Decision Service (Python)Python · FastAPI · Jev fastapi-python-postgres/AGENTS.mdFastAPI + Python + PostgreSQL (Async SQLAlchemy & Pydantic v2)FastAPI · Python · PostgreSQL jev-browser-agent/AGENTS.mdJev Browser Agent (Playwright + TypeSafe System One)Jev · Playwright · TypeScript