Getting Started

Mondel is a lightweight TypeScript ODM for MongoDB.
If you know the MongoDB Node driver, you know Mondel — same filters and operators, with typed collections and Zod validation on top.

Requirements

Component	Supported
Node.js	18+ (20+ recommended with mongodb@7)
MongoDB server	6.0 – 8.x
mongodb peer	^6 or ^7
zod peer	^3.24 or ^4
TypeScript	5.0+ recommended

See Compatibility for details.

Installation

npm

npm install mondel mongodb zod

pnpm

pnpm add mondel mongodb zod

yarn

yarn add mondel mongodb zod

bun

bun add mondel mongodb zod

Five-minute path

1. Define a schema

// src/db/schemas.ts
import { defineSchema, s } from "mondel";

export const userSchema = defineSchema("users", {
  timestamps: true,
  fields: {
    // _id is implicit (ObjectId)
    email: s.string().required().email().unique(),
    name: s.string(),
    role: s.enum(["ADMIN", "USER"]).default("USER"),
  },
});

// `as const` is required for full client type inference
export const schemas = [userSchema] as const;

2. Create a client

Serverless / Edge (Workers, Lambda, Vercel Edge) — factory, connect per request:

// src/db/client.ts
import { createClient, type SchemasToClient } from "mondel";
import { schemas } from "./schemas";

export type DbClient = SchemasToClient<typeof schemas>;

export const connect = createClient({
  serverless: true,
  schemas,
  validation: "strict",
});

Long-running Node (Express, Fastify, Nest) — connect once at startup:

import { createClient } from "mondel";
import { schemas } from "./schemas";

export const db = await createClient({
  uri: process.env.MONGODB_URI!,
  schemas,
  validation: "strict",
});

3. Query

const db = await connect(process.env.MONGODB_URI!);

const created = await db.users.create({
  email: "hello@mondel.dev",
  name: "Ada",
  // role defaults to "USER"
});

const user = await db.users.findOne({ email: "hello@mondel.dev" });

const admins = await db.users.findMany(
  { role: "ADMIN" },
  { sort: { createdAt: -1 }, limit: 20 }
);

await db.close();

4. Push indexes (deploy / CI — not on cold start)

# After building a module that exports `schemas`
npx mondel push --uri "$MONGODB_URI" --schema ./dist/schemas.js --apply-validators

syncIndexes on createClient is deprecated. Prefer the CLI.

Project layout (recommended)

src/db/
  schemas.ts      # defineSchema + export const schemas = [...] as const
  client.ts       # createClient factory or singleton
mondel.config.ts  # optional CLI config

What you get

• Typed collection access — db.users, not db.collection("users")
• Runtime validation on writes (strict | loose | off)
• Field defaults applied on create when validation is on
• Native MongoDB filters, $set / $inc, sessions, aggregation
• Escape hatch — db.users.getCollection() for anything else

What Mondel is not

• Not Mongoose (no middleware cascade, virtuals, or automatic populate)
• Not Prisma (no relation engine or full migration framework)
• Not a new query DSL — you write MongoDB queries

See Comparison and Concepts.

Next

Goal	Page
Mental model	Concepts
All field types	Schemas / Field types
Connection patterns	Client
Workers / Express	Recipes
Coming from Mongoose	Migrate
AI agents	LLM reference