Zenstack Project Setup

ZenStack V3 — Project Setup & Migrations

ZenStack V3 is a TypeScript database toolkit with a Prisma-compatible ORM API built on Kysely (no Rust/WASM). The schema is written in ZModel (.zmodel), a superset of the Prisma schema language. This skill covers installing, scaffolding, the CLI, and migrations. For schema syntax see zenstack-schema-modeling; for queries see zenstack-querying; for access control see zenstack-access-control.

Always confirm exact package versions and commands against the live docs at https://zenstack.dev/docs when something looks off — V3 evolves quickly.

Prerequisites

• Node.js v20+
• TypeScript v5.8.0+
• VSCode extension: "ZenStack V3" (language id zmodel-v3) — distinct from the V2 extension.

Installing

Scaffold a new project (recommended)

npm create zenstack my-project

Initialize ZenStack in an existing project

npx @zenstackhq/cli zen init

Then create zenstack/schema.zmodel and run zen generate.

Manual install

npm install @zenstackhq/schema @zenstackhq/orm
npm install --save-dev @zenstackhq/cli

ZenStack does not bundle database drivers — install one yourself:

Add access control only if needed: npm install @zenstackhq/plugin-policy (see zenstack-access-control).

Project structure

• Schema: zenstack/schema.zmodel (default; override with --schema).
• Generated output: emitted next to the schema (override with --output). Import it as import { schema } from './zenstack/schema'.
• You may commit the generated TypeScript, or .gitignore it and run zen generate in CI.

The zen CLI

The CLI is invoked as zen (or zenstack — equivalent). Add scripts to package.json:

{
  "scripts": {
    "generate": "zen generate",
    "db:push": "zen db push",
    "migrate:dev": "zen migrate dev",
    "migrate:deploy": "zen migrate deploy"
  }
}

Migration commands wrap Prisma Migrate; @zenstackhq/cli has a peer dependency on prisma that is installed automatically when needed.

For the full migration story — migrate dev/deploy/reset/status/resolve, db push/pull, seeding, --create-only, and deployment-pipeline guidance — see the zenstack-db-migration skill.

Workflows

Development loop

1. Edit zenstack/schema.zmodel.
2. zen generate (regenerate types).
3. zen db push to try changes locally without a migration, or zen migrate dev to create a reviewable, committable migration file.
4. Review the migration SQL, then commit it.

Production deploy

zen migrate deploy

Adopt ZenStack on an existing database

1. zen init
2. Set the datasource url in zenstack/schema.zmodel.
3. zen db pull to generate the schema from the DB.
4. Refine it (add access policies, computed fields, etc.).
5. zen generate.

Migrating from Prisma

See the dedicated zenstack-migrate-from-prisma skill — it walks through swapping dependencies, converting schema.prisma to ZModel, replacing PrismaClient with ZenStackClient, updating the generate/migrate scripts, and mapping Prisma custom generators and client extensions.

Migrating from ZenStack V2

See the dedicated zenstack-migrate-from-v2 skill — it covers the package renames, moving access control to the policy plugin, the future() → post-update/before() change, abstract models → types+mixins, the getPrisma → getClient server-adapter change, and the client-side hook migration.

Reference docs

Full ZenStack documentation for this topic is bundled under references/:

• prerequisite.md — supported Node/TypeScript versions, IDE setup
• quick-start.md — scaffolding and the install paths
• cli.md — overview of every zen CLI command
• cli-reference.md — full CLI reference
• migration.md — dev/production migration workflow
• introspection.md — zen db pull from an existing database