Skip to Content
Getting Started

Getting Started

Get up and running with Monkko in just a few minutes. This guide will walk you through installing both packages and setting up your first MongoDB schema.

Installation

Monkko consists of two packages that work together:

  • @monkko/orm - The runtime ODM for your application
  • @monkko/cli - The code generation tool

Install both packages:

# Install the ODM package
pnpm add @monkko/orm
 
# Install the CLI as a dev dependency
pnpm add -D @monkko/cli

Initialize Your Project

Start by initializing Monkko in your project:

pnpm monkko init

This creates a project structure like this:

    • monkko.config.json
      • User.monkko.ts
      • Organisation.monkko.ts

Configure Your MongoDB Connection

Edit the generated monkko.config.json to configure your MongoDB connection:

{
  "mongoUri": "mongodb://localhost:27017",
  "schemasDir": "./schemas",
  "outputDir": "./types/monkko"
}

For production, use environment variables:

{
  "mongoUri": "${MONGODB_URI}",
  "schemasDir": "./schemas", 
  "outputDir": "./types/monkko"
}

Create Your First Schema

Create a schema file in the schemas/ directory:

// schemas/User.monkko.ts
import { defineSchema, fields } from '@monkko/orm'
 
export const User = defineSchema({
  name: "User",
  db: "myapp", // Database name (uses mongoUri from config)
  collection: "users",
  fields: {
    name: fields.string({ required: true }),
    email: fields.string({ required: true, unique: true }),
    age: fields.number({ optional: true }),
    createdAt: fields.date({ default: () => new Date() }),
    updatedAt: fields.date({ default: () => new Date() })
  }
});

Generate Types and Models

Run the CLI to generate TypeScript types and models:

pnpm monkko generate

This creates:

  • TypeScript interfaces for your schemas
  • Zod validation schemas
  • Fully typed model instances
  • Query builder types

Use Your Models

Import and use your generated models:

// Import the generated model
import { userModel } from './types/monkko/User.types'
 
// Create a new user
const newUser = await userModel.create({
  name: "John Doe",
  email: "john@example.com",
  age: 30
});
 
// Find users with type safety
const users = await userModel
  .find({ age: { $gte: 18 } })
  .toJSON();
 
// Update with validation
const updated = await userModel.updateById(userId, {
  name: "Jane Doe"
});

Working with Multiple Databases

Each schema can specify its own database. This allows you to organize your data across multiple databases within the same MongoDB cluster:

// schemas/User.monkko.ts
export const User = defineSchema({
  name: "User",
  db: "users", // Users database
  collection: "users",
  fields: {
    name: fields.string({ required: true }),
    email: fields.string({ required: true, unique: true }),
    organisationId: fields.objectId({ optional: true })
  }
});
 
// schemas/Organisation.monkko.ts  
export const Organisation = defineSchema({
  name: "Organisation",
  db: "organisations", // Separate organisations database
  collection: "organisations",
  fields: {
    name: fields.string({ required: true }),
    website: fields.string({ optional: true })
  }
});
 
// schemas/Product.monkko.ts
export const Product = defineSchema({
  name: "Product", 
  db: "inventory", // Another separate database
  collection: "products",
  fields: {
    name: fields.string({ required: true }),
    price: fields.number({ required: true }),
    organisationId: fields.objectId({ required: true })
  }
});

Working with References

Define relationships between your schemas, even across different databases:

// schemas/User.monkko.ts (updated with reference)
export const User = defineSchema({
  name: "User", 
  db: "users",
  collection: "users",
  fields: {
    name: fields.string({ required: true }),
    email: fields.string({ required: true, unique: true }),
    organisation: fields.reference("Organisation", { optional: true }),
    // ... other fields
  }
});

After regenerating, you can populate references:

// Populate the organisation reference
const usersWithOrgs = await userModel
  .find({})
  .populate("organisation")
  .toJSON();
 
// TypeScript knows organisation is now the full object!
// usersWithOrgs[0].organisation.name ← Fully typed!

Environment Variables

For production, use environment variables in your config:

{
  "mongoUri": "${MONGODB_URI}",
  "schemasDir": "./schemas",
  "outputDir": "./types/monkko"
}

Set your environment variables:

export MONGODB_URI="mongodb://localhost:27017"

Next Steps

Now that you have Monkko set up:

  1. Explore Field Types - Learn about all available field types and options
  2. Advanced Queries - Discover the full query builder API
  3. Validation - Customize Zod validation schemas
  4. Multi-Database - Set up multiple database connections
  5. Performance - Optimize queries and indexes

Need Help?

Ready to build something amazing? Let’s go! 🚀

Last updated on
Examples