InstallationSupported

zmdb is an ESM-only TypeScript backend framework targeting Node.js 26+ and TypeScript 7+. Install @zmdb/core for schema, validation, ORM, migrations, configuration, CLI, application lifecycle and HTTP, with SQLite included. Add jobs, other database providers and protocol integrations only when the application selects them. The server journey demonstrates these choices in one application; the package reference lists the independently usable owners.

Recommended: one product install#

yarn add @zmdb/core@1.0.0-beta.2

import { defineRepository, is, schemaOf, type CreateDTO, type Entity, type PrimaryKey, type Serial, type Sql, type Table } from '@zmdb/core';
import { sqliteDriver } from '@zmdb/core/sqlite';

The @zmdb/core package re-exports the curated public API of its required workspace dependencies, with complete concerns under @zmdb/core/schema, @zmdb/core/sql, @zmdb/core/validator, @zmdb/core/orm, @zmdb/core/web, @zmdb/core/compiler, @zmdb/core/migrations, and @zmdb/core/testing. SQLite is included by default and exposed through @zmdb/core/sqlite. Each database package owns its compiler traits, migrations, introspection and structural driver. The @zmdb/core/postgres, @zmdb/core/mysql, @zmdb/core/mssql, @zmdb/core/cockroach and @zmdb/core/singlestore facades resolve when their optional database package is installed. The @zmdb/core/web facade combines the protocol-neutral @zmdb/app kernel with the HTTP-specific @zmdb/web package.

The focused @zmdb/core/tags, @zmdb/core/derive, @zmdb/core/ir, @zmdb/core/dto, and @zmdb/core/relations entries expose their documented concerns. Type-only imports from either the root or those paths disappear from emitted JavaScript.

@zmdb/mysql is independently installable and is not pulled in by the default product. Install it with mysql2 when the application selects MySQL; importing the package does not load the client.

@zmdb/core/tags and @zmdb/core/derive are types only — nothing there has a runtime export, so those two imports vanish entirely from your build output.

Applications that publish an HTTP API add the independently installable @zmdb/client runtime beside their generated module. The Generated HTTP Client guide shows one contract feeding runtime routing, OpenAPI, and browser/Node client output.

Applications then add only the framework adapter that owns their UI lifecycle or request boundary. The Client Applications guide starts from that one generated client, compares all nine supported frameworks, and links to their framework-native lifecycle, SSR, hydration, cancellation, and testing recipes. Six of the nine ship as entry points of @zmdb/client; Next.js, Nuxt and SvelteKit own their own packages because each integrates with a server framework rather than only a UI runtime.

Optional server integrations#

yarn add @zmdb/core@1.0.0-beta.2 installs none of the packages or peers below. Add only the integration selected by the application:

Install the package; import the entry. A subpath is never an install target, so @zmdb/transport carries every broker and gRPC adapter and @zmdb/app/otel ships inside the application kernel. Each adapter's external client is an optional peer of its package, so installing the package installs no broker, gRPC or OpenTelemetry client — add only the peer named beside the entry you import.

The package owns the adapter; the peer owns the external protocol client. @zmdb/app owns transport-neutral messaging and observability ports, while @zmdb/jobs owns queue and worker behavior. @zmdb/compiler owns TypeScript reflection and emission; @zmdb/protobuf owns the calls, service-artifact types, and generated wire runtime that emitted code imports.

Alpha migration: replace any branch-only or pre-release zmdb/jobs import with @zmdb/jobs, and replace zmdb/jobs/schedule with @zmdb/jobs/schedule. The default product does not ship a compatibility facade or automatically install jobs.

Prerequisites#

• Node.js 26.0.0 or later
• TypeScript 7.0.2 or later
• ESM — your package.json must have "type": "module"

{
  "type": "module",
  "dependencies": {
    "@zmdb/core": "^1.0.0-beta.2"
  }
}

Advanced: install sub-packages individually#

Choose runtime dependencies separately from the build tools. For example, a standalone SQLite data layer can use:

yarn add @zmdb/schema@1.0.0-beta.2 @zmdb/sql@1.0.0-beta.2 @zmdb/validator@1.0.0-beta.2 @zmdb/orm@1.0.0-beta.2 @zmdb/sqlite@1.0.0-beta.2
yarn add --dev @zmdb/compiler@1.0.0-beta.2 typescript@^7.0.2

Install @zmdb/cli@1.0.0-beta.2 with TypeScript instead when you want the single zmdb command; it includes the compiler and migrations engines. Install @zmdb/migrations@1.0.0-beta.2 directly when code owns the snapshot, plan or runner workflow. The tooling guide explains config ownership, optional adapter peers and which entries belong in generated runtime code.

Install Individual Packages#

Install only what you need:

# Schema definition + type derivation
yarn add @zmdb/schema

# Query builder (SELECT/INSERT/UPDATE/DELETE)
yarn add @zmdb/sql

# Schema snapshots, migration plans, runners, introspection, and declaration emission
yarn add @zmdb/migrations@1.0.0-beta.2

# Runtime validation + serialization
yarn add @zmdb/validator

# TypeScript reflection, AOT emission, build adapters, and lint rules
yarn add --dev @zmdb/compiler@1.0.0-beta.2 typescript@^7.0.2

# The single zmdb executable for codegen, migrations and application commands
yarn add --dev @zmdb/cli@1.0.0-beta.2 typescript@^7.0.2

# Repository with CRUD + transactions
yarn add @zmdb/orm

# Complete SQLite dialect + migrations + introspection + node:sqlite driver
yarn add @zmdb/sqlite

# Complete SQL Server vertical plus the application-selected client
yarn add @zmdb/mssql mssql

# Complete PostgreSQL dialect + migrations + introspection + structural pg driver
yarn add @zmdb/postgres pg

# Complete MySQL vertical + consumer-selected client
yarn add @zmdb/mysql mysql2

# Protocol-neutral application kernel
yarn add @zmdb/app

# HTTP framework over the application kernel
yarn add @zmdb/web

# Portable queues, workers, and scheduling with explicit storage providers
yarn add @zmdb/jobs

# SQLite persistence or an owned memory store
yarn add @zmdb/jobs @zmdb/jobs-sqlite

# Optional PostgreSQL jobs adapter
yarn add @zmdb/jobs @zmdb/jobs-postgres pg@^8.23.0

# Dependency-free generated-client runtime
yarn add @zmdb/client

# React generated-client lifecycle bindings, imported from @zmdb/client/react
yarn add @zmdb/client react@19

# React Native AppState, connectivity, and credential-store lifecycle, from @zmdb/client/react-native
yarn add @zmdb/client react@19 react-native@0.87

# Angular dependency injection, signals, and Observable cancellation, from @zmdb/client/angular
yarn add @zmdb/client @angular/core@22 rxjs@7

# Vue plugin and lifecycle composables, from @zmdb/client/vue
yarn add @zmdb/client vue@^3.5

# Svelte context and lifecycle-aware stores, from @zmdb/client/svelte
yarn add @zmdb/client svelte@^5.57

# SvelteKit request-local server/client loads and navigation cancellation
yarn add @zmdb/sveltekit @sveltejs/kit@^2.70 svelte@^5.57

# Next App Router request scopes and browser bindings
yarn add @zmdb/next next@16 react@19 react-dom@19

# Solid context, resources, and owner-lifetime cancellation, from @zmdb/client/solid
yarn add @zmdb/client solid-js@1

# Nuxt module, request-scoped Nitro transport, and Vue hydration
yarn add @zmdb/nuxt nuxt@^4.5 vue@^3.5

# Dependency-free protobuf and typed gRPC artifacts
yarn add @zmdb/protobuf

# Typed gRPC server and client adapter, imported from @zmdb/transport/grpc
yarn add @zmdb/protobuf @zmdb/transport @grpc/grpc-js@^1.14.0

# Core NATS transport strategy, from @zmdb/transport/nats
yarn add @zmdb/transport @nats-io/transport-node@^3.4.0

# RabbitMQ transport strategy, from @zmdb/transport/rabbitmq
yarn add @zmdb/transport amqplib@^2.0.1

# Redis Pub/Sub transport strategy, from @zmdb/transport/redis
yarn add @zmdb/transport redis@^6.2.1

# Provider-neutral AI tools + bounded chat
yarn add @zmdb/ai

# Optional Anthropic chat driver, from @zmdb/ai/anthropic
yarn add @zmdb/ai @anthropic-ai/sdk@0.124.0

# LangChain structured-tool integration, from @zmdb/ai/langchain
yarn add @zmdb/ai @langchain/core@^1.2.9

# Vercel AI SDK tool adapter, from @zmdb/ai/vercel
yarn add @zmdb/ai ai@^7.0.93

# Transport-neutral MCP client/server core
yarn add @zmdb/ai @zmdb/mcp

# OpenTelemetry API adapter, from @zmdb/app/otel
yarn add @zmdb/app @opentelemetry/api@^1.9.0

TypeScript Configuration#

Ensure your tsconfig.json targets modern features:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*.ts"]
}

The build step#

zmdb declares tables as types, and a type does not exist at runtime. The transformer is what closes that gap: it reads the declaration from the type checker and replaces each schemaOf<T>(), assert<T>(), is<T>(), validate<T>(), equals<T>(), assertEquals<T>(), random<T>() and toJsonSchema<T>() call with the reflected result.

// vite.config.ts / rollup / esbuild / webpack — one factory for all
import { zmdbAot } from '@zmdb/core/compiler';

const plugin = await zmdbAot({ project: new URL('./tsconfig.json', import.meta.url).pathname });
export default {
  plugins: [plugin],
};

@zmdb/core/compiler discovers zmdb.config.ts when project is omitted. If neither config nor an explicit project or session is available, the plugin cannot ask the checker what a type is, so it leaves every f<T>(…) call alone — and an untransformed schemaOf<T>() throws when called. A refused call site is a build error by default, not a silent fallback. See AOT Setup.

For a project that only needs the query compiler, there is no build step at all — see Pure TypeScript.

Verify Installation#

The query compiler is plain runtime code, so it verifies the install without the transformer in the way:

import { createQueryCompiler, trustedTable } from '@zmdb/core/sql';
import { sqlite } from '@zmdb/core/sqlite';

const q = createQueryCompiler(sqlite).selectFrom(trustedTable('users')).select(['id']).compile();
console.log(q.text); // SELECT "id" FROM "users"

Then verify the transformer is wired, which is the part that actually goes wrong:

import { schemaOf, type PrimaryKey, type Serial, type Sql, type Table } from '@zmdb/core';

interface User extends Table<'users'> {
  id: number & Sql<'integer'> & Serial & PrimaryKey;
  email: string & Sql<'text'>;
}

const userSchema = schemaOf<User>();
console.log(userSchema.table); // 'users'
const emailColumn = userSchema.columns.email;
if (emailColumn === undefined) throw new Error('The generated User schema must contain email');
console.log(emailColumn.type); // 'text'

If that throws instead of printing, the plugin is not running over this file.

Package Overview#

Each row is a specifier you import. Where it is a subpath, install the package before the first slash.

Renamed in 1.0.0-beta.3#

Sixteen single-purpose packages became entry points of four, taking the published set from 42 packages to 27. Each old package installed one small adapter and dragged its own version, changelog entry and peer block behind it; folding them removes that overhead without changing any exported API. The names below were unpublished rather than deprecated in place, so there is no compatibility stub to install and no warning to silence: replace the dependency with the package on the right and the import with the entry point on the right.

@zmdb/next, @zmdb/nuxt and @zmdb/sveltekit keep their own names. @zmdb/transport has no root export: import a transport subpath directly.

Next Steps#

• Quick Start — declare your first table
• Schema Declaration — how a type becomes a table
• Tag Reference — the full tag vocabulary
• AOT Setup — configure the transformer
• Pure TypeScript — what works with no build step
• Generated HTTP Client — emit OpenAPI and a typed client from one HTTP contract
• Client Applications — use that one client through React, Angular, Vue, Svelte, Solid, React Native, Next.js, Nuxt, or SvelteKit