Installation

Requirements

• Node.js 22+ (required for the CLI)
• TypeScript (the CLI uses tree-sitter-typescript to parse models)

Quick setup

pnpm dlx @jsorm/cli configure

The interactive assistant installs the necessary dependencies, detects your framework, runtime, package manager, and TypeScript. It generates jsorm.config.ts at the project root.

Manual installation

If you prefer to install dependencies manually:

1. Install dependencies

# CLI (required to run commands)
pnpm add -D @jsorm/cli

# Core + Client
pnpm add @jsorm/client @jsorm/core

# Provider (example: PostgreSQL)
pnpm add @jsorm/provider-pg-node

2. Add script

Add the jsorm script to your package.json for convenience:

{
  "scripts": {
    "jsorm": "jsorm"
  }
}

This allows you to run pnpm jsorm instead of pnpm exec jsorm for all subsequent commands.

3. Configure

You can use the interactive CLI:

pnpm jsorm configure

Or create jsorm.config.ts directly at the project root:

import { defineConfig } from "@jsorm/core";

export default defineConfig({
  models: "src/models",
  databases: {
    main: {
      access: "server",
      provider: "postgres-node",
      options: {
        naming: { fields: "snake_case" },
      },
    },
  },
});

See Configuration for all options.

4. Define models

Create your models in src/models/:

import { defineModel, t, r } from "@jsorm/core";

export const User = defineModel("users", {
  db: "main",
  fields: {
    id: t.uuid().primary().autoCreate(),
    name: t.string(100),
    email: t.string(255).unique(),
    password: t.string(255).hidden(), // not null, with hidden it won't be included in queries
    active: t.boolean().default(true),
    createdAt: t.dateTime().autoCreate(),
  },
  relations: {
    posts: r.hasMany("post"),
  },
});

5. Generate types

pnpm jsorm gen

This generates the runtime and types files:

• .jsorm/types.ts — Record interfaces, query types, DB, DBClient
• src/models/jsorm.server.ts — Server instance with createJsorm<DB>
• src/models/jsorm.client.ts — Client instance (only if there are client models)

Import from the generated file:

import { jsorm } from "./models/jsorm.server.js";

// Main database
const { data: users } = await jsorm.users.get();

// Non-main database
const { data: sessions } = await jsorm.cache.sessions.get();

Model structure

Models are organized by database:

src/
    models/
        jsorm.server.ts          ← generated (server access)
        jsorm.client.ts          ← generated (if there are client databases)
        server/
            main/
                User.ts
                Role.ts
                Post.ts
            cache/
                Session.ts
        client/
            main/
                Todo.ts

main is always the default database.