Skip to content

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 ​

ComponentSupported
Node.js18+ (20+ recommended with mongodb@7)
MongoDB server6.0 – 8.x
mongodb peer^6 or ^7
zod peer^3.24 or ^4
TypeScript5.0+ recommended

See Compatibility for details.

Installation ​

bash
npm install mondel mongodb zod
bash
pnpm add mondel mongodb zod
bash
yarn add mondel mongodb zod
bash
bun add mondel mongodb zod

Five-minute path ​

1. Define a schema ​

typescript
// 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:

typescript
// 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:

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

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

3. Query ​

typescript
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) ​

bash
# 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.

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 ​

GoalPage
Mental modelConcepts
All field typesSchemas / Field types
Connection patternsClient
Workers / ExpressRecipes
Coming from MongooseMigrate
AI agentsLLM reference

Released under the MIT License. · llms.txt