Getting Started

From zero to a working data layer in 5 minutes. No database, no Docker, no existential crisis.

Step 1: Install SeedORM

$ npm install seedorm

Step 2: Initialize a project

Create a new directory for your project and initialize it:

$ mkdir my-app && cd my-app
$ seedorm init
✓  Created seedorm.config.json
✓  Created data/ directory
✓  Created migrations/ directory

That's it. No database connection strings, no environment variables, no crying. Your data will be stored in data/seedorm.json, which is just a plain JSON file you can open and read like a normal human being.

Step 3: Define a model

Create a file for your application logic. Models define the shape and constraints of your data. Think of them as the contract between "what you think your data looks like" and "what it actually looks like."

app.tstypescript
1import { SeedORM, FieldType } from "seedorm";
2
3async function main() {
4  // Create a SeedORM instance (defaults to JSON adapter)
5  const db = new SeedORM();
6  await db.connect();
7
8  // Define a User model
9  const User = db.model({
10    name: "User",
11    collection: "users",
12    schema: {
13      name:  { type: FieldType.String, required: true, minLength: 1, maxLength: 100 },
14      email: { type: FieldType.String, required: true, unique: true },
15      age:   { type: FieldType.Number, min: 0, max: 150 },
16      role:  { type: FieldType.String, enum: ["admin", "user", "moderator"], default: "user" },
17      active:{ type: FieldType.Boolean, default: true },
18    },
19    prefix: "usr",  // IDs will look like usr_V1StGXR8_Z5j
20  });
21
22  // Initialize the collection (creates it if it doesn't exist)
23  await User.init();
24
25  // ... your app logic goes here (see below) ...
26
27  await db.disconnect();
28}
29
30main();

Step 4: Create and query data

Create documents

app.tstypescript
// Create a single document
const alice = await User.create({
  name: "Alice Johnson",
  email: "alice@example.com",
  age: 30,
  role: "admin",
});
console.log(alice);
// {
//   id: "usr_7pplmrxTXJxu",
//   name: "Alice Johnson",
//   email: "alice@example.com",
//   age: 30,
//   role: "admin",
//   active: true,           // default applied
//   createdAt: "2025-...",
//   updatedAt: "2025-..."
// }
// Create multiple documents at once
const users = await User.createMany([
  { name: "Bob Smith", email: "bob@example.com", age: 25 },
  { name: "Charlie Brown", email: "charlie@example.com", age: 35 },
]);

Query with filters

app.tstypescript
// Find all users older than 25, sorted by name
const results = await User.find({
  filter: { age: { $gt: 25 } },
  sort: { name: 1 },
});
// Find one user by email
const user = await User.findOne({ email: "alice@example.com" });
// Find by ID
const found = await User.findById("usr_7pplmrxTXJxu");
// Count documents
const total = await User.count();
const adminCount = await User.count({ role: "admin" });

Update and delete

app.tstypescript
// Update a document (partial update)
const updated = await User.update(alice.id, {
  age: 31,
  role: "moderator",
});
// Delete a document
await User.delete(alice.id);
// Delete multiple with a filter
const deletedCount = await User.deleteMany({ active: false });

Define relations between models

SeedORM also supports relations like hasOne, hasMany, belongsTo, and manyToMany, so you can populate related documents with a single query. See the Relations page for details and examples.

Step 5: Use the dev server

SeedORM ships with a built-in REST API server so you can test your data with curl, Postman, or whatever your frontend framework is this week:

$ npx seedorm start
✓  Connected to database
seedorm dev server
info  Listening on http://localhost:4100
REST API: GET/POST/PUT/DELETE /api/:collection/:id

Now you can interact with your data via HTTP:

# Register a model
$ curl -X POST http://localhost:4100/api/models \
  -H 'Content-Type: application/json' \
  -d '{"name":"Todo","collection":"todos","schema":{"title":"string","done":"boolean"}}'
# Create a document
$ curl -X POST http://localhost:4100/api/todos \
  -H 'Content-Type: application/json' \
  -d '{"title":"Learn seedorm","done":false}'
# List all documents
$ curl http://localhost:4100/api/todos
# Update a document
$ curl -X PATCH http://localhost:4100/api/todos/doc_abc123 \
  -H 'Content-Type: application/json' \
  -d '{"done":true}'

Step 6: Browse with Studio

If you're more of a visual person (no judgment), launch Studio to browse and edit your data in a real UI:

$ npx seedorm studio
✓  Connected to database
seedorm studio
info  Open http://localhost:4200 in your browser

Next steps