Installation

Prerequisites

Node.js 24 or higher for the CLI, migrations, and native adapters
TypeScript 5.0 or higher (strict: true recommended)
pnpm, npm, or bun

Choose your package set

Start with the package combination that matches where your code runs:

pnpm add @jsorm/core @jsorm/node @jsorm/pg pg

pnpm add @jsorm/core @jsorm/node @jsorm/mysql mysql2

pnpm add @jsorm/core @jsorm/node @jsorm/sqlite sqlite3

bun install @jsorm/core @jsorm/node @jsorm/pg pg

bun install @jsorm/core @jsorm/node @jsorm/sqlite

pnpm add @jsorm/runtime @jsorm/fetch
pnpm add -D @jsorm/node @jsorm/pg pg

For edge apps, @jsorm/runtime + @jsorm/fetch owns request-time queries, while @jsorm/core (CLI) plus @jsorm/node and a native adapter stays in CI/release jobs for jsorm deploy, migrations, and other CLI work.

Bootstrap config with `jsorm init`

After installing @jsorm/core, run the CLI to scaffold config and project helpers:

pnpm exec jsorm init
# or, to run without local install:
pnpm dlx @jsorm/core init

Schema path detection — prompts only if src/schema/ does not yet exist (default src/schema/index.ts)
Schema file generation — creates src/schema/index.ts and an example User model at src/schema/main/user.ts (only if they don’t already exist)
Database / adapter setup — loops to collect one or more database connections (name + dialect). If jsorm.config.ts already exists, existing connection sources are preserved and only missing databases are prompted.
Writes jsorm.config.ts — connection sources and runtime config inline, ready to edit
Generates runtime helpers (db.ts by default, jsormdb.ts fallback if needed) for the Node runtime path
Creates .env with a DATABASE_URL placeholder (if one doesn’t exist)
Creates .migrations/schema.json — empty snapshot for migration generation
Verifies bootstrap + worker readiness before reporting init success

Use --no-migrations to skip migration scaffolding entirely (no .migrations/ directory, no migrations block in config).

Generated `jsorm.config.ts`

After init, your project has a central config file that both runtime code and the CLI can share in Node-capable workflows:

// jsorm.config.ts
import { defineConnectionSource, defineJsormConfig } from '@jsorm/core';
import { pgAdapter } from '@jsorm/pg';

const main = defineConnectionSource({
  adapter: pgAdapter({
    name: 'main',
    connectionString: process.env.DATABASE_URL!,
    pool: { min: 2, max: 10 },
  }),
});

export default defineJsormConfig({
  connectionSources: { main },
  defaults: {
    connectionSource: 'main',
  },
});

Node runtime instances can resolve this file during createJsorm().init(). In edge or fetch-only apps, define the same shape with @jsorm/runtime and pass it explicitly.

Packages

Package	Purpose	Peer dependency
`@jsorm/core`	Node-capable authoring/runtime package for models, queries, config, and migration primitives	—
`@jsorm/runtime`	Runtime-safe package for edge or fetch-only application code	—
`@jsorm/node`	Runtime for Node and Bun (on Bun, uses native Bun APIs, no Rust engine)	—
`@jsorm/fetch`	HTTP/fetch transport for runtime-safe edge access	—
`@jsorm/pg`	PostgreSQL native adapter	`pg`
`@jsorm/mysql`	MySQL native adapter	`mysql2`
`@jsorm/sqlite`	SQLite native adapter	`sqlite3`

Install only the runtime and adapter packages you actually use.

Runtime boundary reminder

TypeScript configuration

Ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "strict": true,
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  }
}

Best practices

Install the package set that matches your runtime boundary first, then run pnpm exec jsorm init from a project that has @jsorm/core.
Keep DATABASE_URL and other credentials in .env, never committed to source.
Use strict: true in tsconfig.json for full type inference.
Keep one jsorm.config.ts per deploy owner, and separate edge runtime imports from Node CLI ownership.