Installation

Prerequisites

• Node.js 18 or higher
• TypeScript 5.0 or higher (strict: true recommended)
• pnpm, npm, or bun

Caution

jsorm requires a Rust engine binary at runtime. The init command provisions it automatically. Without the binary, execution stops with an explicit error — there is no silent TypeScript fallback.

Bootstrap with jsorm init

The recommended entry point for any new project is the interactive jsorm init command. It handles everything: adapter selection, package installation, engine binary provisioning, and config file generation.

pnpm

pnpm dlx jsorm@latest init

npm

npx jsorm@latest init

bun

bunx jsorm@latest init

1. Prompts for schema entry path — defaults to src/schema/index.ts

2. Generates schema structure with an example User model:

   src/schema/main/user.ts
   src/schema/index.ts

3. Prompts for adapter(s) — installs the adapter package and its driver peer dependency

4. Provisions the Rust engine binary into node_modules/.jsorm/engine, verifies checksum and executable permissions

5. Writes jsorm.config.ts — connection and migration sources inline, ready to edit

6. Creates .env with a DATABASE_URL placeholder (if one doesn’t exist)

7. Creates .migrations/schema.json — empty snapshot for migration generation

Generated jsorm.config.ts

After init, your project has a central config file that both the runtime and CLI share:

// jsorm.config.ts
import { defineConnectionSource, defineJsormConfig } from 'jsorm';
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',
  },
});

The global jsorm singleton automatically lazy-loads this file from process.cwd() on first use.

Packages

Package	Purpose	Peer dependency
jsorm	Core ORM, singleton runtime, config, migrations, CLI	—
jsorm-pg	PostgreSQL adapter	pg
jsorm-mysql	MySQL adapter	mysql2
jsorm-sqlite	SQLite adapter	sqlite3

Only install adapters you actually use.

Engine binary lookup order

1. JSORM_ENGINE_PATH environment variable
2. node_modules/.jsorm/engine/jsorm-engine (.exe on Windows)
3. Legacy .jsorm/bin/jsorm-engine

If the binary is missing or integrity check fails, jsorm throws a blocking error with an actionable message:

[JSORM ENGINE MISSING] Run: pnpx jsorm init
[JSORM ENGINE INVALID] Integrity check failed
[JSORM VERSION MISMATCH] Incompatible AST/Engine versions

Edge runtime note

Caution

jsorm requires Node.js runtime. Edge runtimes are explicitly blocked. In Next.js App Router add export const runtime = "nodejs" to each route handler that uses jsorm.

TypeScript configuration

Ensure your tsconfig.json includes:

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

Best practices

1. Always use pnpm dlx jsorm@latest init for new projects — it ensures engine and config are correctly wired.
2. Keep DATABASE_URL and other credentials in .env, never committed to source.
3. Use strict: true in tsconfig.json for full type inference.
4. One jsorm.config.ts per project — used by both runtime and CLI.