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.)
- Author
- zenstackhq ↗
- Repository
- skills ↗
- Licence
- MIT
- Last repository change
- 28.10.2026
Assessment and security
- Files in this package
- 7
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 28.10.2026, without references to retired models or APIs.
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
- Prerequisites
- Installing
- Project structure
- The zen CLI
- Workflows
- Migrating from Prisma
- Migrating from ZenStack V2
- Reference docs
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.…