Skip to content
Skills Library
Programming · Automation

zenstack-project-setup

/zenstack-project-setup

Set up, configure, and manage a ZenStack V3 project. Use when installing ZenStack, scaffolding a new project, or running the `zen` CLI (generate). (For database schema migrations use zenstack-db-migration; to migrate a Prisma project use zenstack-migrate-from-prisma; to upgrade from ZenStack V2 use zenstack-migrate-from-v2.)

Repository
skills ↗
Licence
MIT
Last repository change
28.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
7
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 28.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Set up, configure, and manage a ZenStack V3 project. Use when installing ZenStack, scaffolding a new project, or running the `zen` CLI (generate). (For database schema migrations use zenstack-db-migration; to migrate a Prisma project use zenstack-migrate-from-prisma; to upgrade from ZenStack V2 use zenstack-migrate-from-v2.)

Original author description

Set up, configure, and manage a ZenStack V3 project. Use when installing ZenStack, scaffolding a new project, or running the `zen` CLI (generate). (For database schema migrations use zenstack-db-migration; to migrate a Prisma project use zenstack-migrate-from-prisma; to upgrade from ZenStack V2 use zenstack-migrate-from-v2.)

How it works

  1. Prerequisites
  2. Installing
  3. Project structure
  4. The zen CLI
  5. Workflows
  6. Migrating from Prisma
  7. Migrating from ZenStack V2
  8. Reference docs
Original SKILL.md headings · 140 lines, 777 words
SKILL.md preview
---
name: zenstack-project-setup
description: Set up, configure, and manage a ZenStack V3 project. Use when installing ZenStack, scaffolding a new project, or running the `zen` CLI (generate). (For database schema migrations use zenstack-db-migration; to migrate a Prisma project use zenstack-migrate-from-prisma; to upgrade from ZenStack V2 use zenstack-migrate-from-v2.)
---

# ZenStack V3 — Project Setup & Migrations

ZenStack V3 is a TypeScript database toolkit with a Prisma-compatible ORM API built on
[Kysely](https://kysely.dev) (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)

```bash
npm create zenstack my-project
```

### Initialize ZenStack in an existing project

```bash
npx @zenstackhq/cli zen init
```

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

### Manual install

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

ZenStack does **not** bundle database drivers — install one yourself:

| Database   | Install |
| ---------- | ------- |
| PostgreSQL | `npm install pg` + `npm install -D @types/pg` |
| MySQL      | `npm install mysql2` |
| SQLite     | `npm install better-sqlite3` + `npm install -D @types/better-sqlite3` |

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`:

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

| Command | Purpose |
| ------- | ------- |
| `zen check` | **Only** validate `schema.zmodel` for syntax and semantic errors — does not regenerate anything. Use when you just want to confirm the schema is valid. |
| `zen generate` | Compile `schema.zmodel` → TypeScript (regenerate the database client); also validates the schema as it compiles. **Run after every schema change**, before using the client. Flags: `--schema <path>`, `--output <path>`. |
| `zen db push` | Push schema to the DB **without** a migration file. Dev/testing only — never in production. |
| `zen db pull` | Introspect an existing DB and update the ZModel schema (v3.4.0+, experimental). Can overwrite your schema — back up / use source control first. |
| `zen migrate dev` | Create a migration from schema changes and apply it (dev only). `--create-only` makes an empty migration to edit by hand (e.g. for views). |
| `zen migrate deploy` | Apply all pending migrations. Use this in your production/deploy pipeline. |
| `zen migrate reset` | Drop all tables and reapply migrations. Dev/testing only. |
| `zen migrate status` | Show applied vs. pending migrations. |
| `zen migrate resolve` | Mark a migration applied/rolled-back without changing the schema (manual recovery). |

> 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**

```bash
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/`](references/):

- [prerequisite.md](references/prerequisite.md) — supported Node/TypeScript versions, IDE setup
- [quick-start.md](references/quick-start.md) — scaffolding and the install paths
- [cli.md](references/cli.md) — overview of every `zen` CLI command
- [cli-reference.md](references/cli-reference.md) — full CLI reference
- [migration.md](references/migration.md) — dev/production migration workflow
- [introspection.md](references/introspection.md) — `zen db pull` from an existing database
Files in this package (7)
  • SKILL.md 6 KB
  • references/cli-reference.md 1 KB
  • references/cli.md 1 KB
  • references/introspection.md 1 KB
  • references/migration.md 1 KB
  • references/prerequisite.md 1 KB
  • references/quick-start.md 1 KB

Versions

The database has no other skills named zenstack-project-setup.

Database snapshot: 13.11.2026 · package version ccab6a2e87b9 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100zenstack-db-migration
    Manage database schema migrations in ZenStack V3. Use when creating/applying migrations (zen migrate dev/deploy/reset/status/resolve), prototyping with zen db push, introspecting an existing database with zen db pull, seeding, handling unsupported features (views) with…
  • 100zenstack-migrate-from-prisma
    Migrate an existing Prisma project to ZenStack V3. Use when replacing Prisma/@prisma/client with ZenStack, converting schema.prisma to ZModel, swapping PrismaClient for ZenStackClient, updating generate/migrate scripts, mapping Prisma custom generators and client extensions, or…
  • 100zenstack-v3
    ZenStack v3 schema-first ORM for TypeScript. Use when working with ZModel schemas, ZenStack ORM CRUD operations, access control policies (@@allow/@@deny), database migrations, server adapters (Next.js, Express), runtime plugins, computed fields, polymorphism, typed JSON, or…
  • 100prisma-cli
    Prisma ORM CLI commands reference covering init, generate, migrate, db, dev, complete, studio, validate, format, debug, and mcp. Use for ORM/database CLI workflows, not the Prisma Platform CLI. Triggers on "prisma init", "prisma generate", "prisma migrate", "prisma db", "prisma…
  • 100prisma-migration
    Creates Prisma schema models and generates database migrations from the entity model. Use when the user asks to "create a migration", "update the schema", "set up database tables", "write a Prisma migration", or mentions schema migration, DB migration, database versioning, or Prisma schema changes.
  • 100prisma-postgres-upgrade
    Upgrade a PostgreSQL app from Prisma ORM 6 or 7 straight to Prisma 8 in one pass, keeping the existing schema.prisma, database and data. Use when a Postgres project on Prisma 6 or 7 wants Prisma 8, including before deploying it on Prisma Compute, which runs only Prisma 8.…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.