Instalación

Requisitos previos

• Node.js 24 o superior para CLI, migraciones y adaptadores nativos
• TypeScript 5.0 o superior (strict: true recomendado)
• pnpm, npm o bun

Precaución

Elige paquetes según el límite de runtime. Usa @jsorm/core o @jsorm/node con adaptadores nativos en Node y Bun, y @jsorm/runtime + @jsorm/fetch para apps edge o fetch-only. La propiedad del CLI pertenece a @jsorm/core. Para deploys, usa @jsorm/core (CLI) + @jsorm/node (runtime) juntos en un entorno Node.

Elige tu set de paquetes

Empieza con la combinación de paquetes que coincide con el entorno donde corre tu código:

Node + PostgreSQL

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

Node + MySQL

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

Node + SQLite

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

Bun + PostgreSQL

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

Bun + SQLite

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

Edge + fetch

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

Para apps edge, @jsorm/runtime + @jsorm/fetch se encarga de las queries en tiempo de request, mientras @jsorm/core (CLI) más @jsorm/node y un adaptador nativo queda en CI/release jobs para jsorm deploy, migraciones y demás tareas CLI.

Bootstrap de config con jsorm init

Después de instalar @jsorm/core, ejecuta el CLI para generar config y helpers del proyecto:

pnpm exec jsorm init
# o, para ejecutar sin instalación local:
pnpm dlx @jsorm/core init

1. Detección de ruta de schema — solo pregunta si src/schema/ no existe (por defecto src/schema/index.ts)

2. Generación de archivos de schema — crea src/schema/index.ts y un modelo User de ejemplo en src/schema/main/user.ts (solo si no existen)

3. Setup de bases/adaptadores — recorre en bucle para recolectar una o más conexiones (nombre + dialecto). Si jsorm.config.ts ya existe, las connection sources existentes se preservan y solo se preguntan las faltantes.

4. Escribe jsorm.config.ts — connection sources y config de runtime inline, listos para editar

5. Genera helpers runtime (db.ts por defecto, jsormdb.ts fallback si aplica) para el camino Node

6. Crea .env con un placeholder de DATABASE_URL (si no existe)

7. Crea .migrations/schema.json — snapshot vacío para generación de migraciones

8. Verifica bootstrap + readiness de workers antes de reportar éxito

Usa --no-migrations para omitir la scaffolding de migraciones por completo (sin directorio .migrations/, sin bloque migrations en config).

jsorm.config.ts generado

Después de init, el proyecto tiene un archivo de configuración central que pueden compartir el runtime y el CLI en flujos Node:

// 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',
  },
});

Las instancias runtime en Node pueden resolver este archivo durante createJsorm().init(). En apps edge o fetch-only, define la misma forma con @jsorm/runtime y pásala explícitamente.

Paquetes

Paquete	Propósito	Peer dependency
@jsorm/core	Paquete de authoring/runtime para Node con modelos, queries, config y primitivas de migración	—
@jsorm/runtime	Paquete runtime-safe para código de aplicación edge o fetch-only	—
@jsorm/node	Runtime para Node y Bun (en Bun, usa APIs nativas de Bun, sin motor Rust)	—
@jsorm/fetch	Transporte HTTP/fetch para acceso edge runtime-safe	—
@jsorm/pg	Adaptador nativo PostgreSQL	pg
@jsorm/mysql	Adaptador nativo MySQL	mysql2
@jsorm/sqlite	Adaptador nativo SQLite	sqlite3

Instala solo los paquetes de runtime y adaptadores que realmente uses.

Recordatorio sobre límites de runtime

Precaución

Las apps edge están soportadas mediante @jsorm/runtime + @jsorm/fetch, pero jsorm init, las migraciones y jsorm deploy siguen perteneciendo a un entorno Node o Bun separado con @jsorm/core (CLI) + @jsorm/node (runtime).

Configuración TypeScript

Asegúrate de que tu tsconfig.json incluya:

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

Buenas prácticas

1. Instala primero el set de paquetes que corresponde a tu runtime y luego ejecuta pnpm exec jsorm init desde un proyecto que tenga @jsorm/core.
2. Mantén DATABASE_URL y otras credenciales en .env, nunca commiteadas al repositorio.
3. Usa strict: true en tsconfig.json para aprovechar la inferencia de tipos completa.
4. Mantén un jsorm.config.ts por owner de deploy y separa los imports edge de la propiedad Node del CLI.