Quick Start

info

All v3 packages are currently published under the "@next" tag.

There are several ways to start using ZenStack ORM.

1. Creating a project from scratch

Run the following command to scaffold a new project with a pre-configured minimal starter:

npm create zenstack@next my-project

Or simply use the following playground to experience it inside the browser.

Interactive Sample

Click here to pop out if the embed doesn't load an interactive terminal.

Plain Code

main.ts

Loading...

2. Adding to an existing project

To add ZenStack to an existing project, run the CLI init command to install dependencies and create a sample schema:

npm

npx zenstack@next init

pnpm

pnpm zenstack@next init

bun

bunx zenstack@next init

yarn

npx zenstack@next init

Then create a zenstack/schema.zmodel file in the root of your project. You can use the following sample schema to get started:

datasource db {
  provider = 'sqlite'
  url = "file:./dev.db"
}

model User {
  id       String @id @default(cuid())
  email    String @unique
  posts    Post[]
}

model Post {
  id        String   @id @default(cuid())
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
  title     String
  content   String
  published Boolean  @default(false)
  author    User     @relation(fields: [authorId], references: [id])
  authorId  String
}

Finally, run zen generate to compile the schema into TypeScript.

npm

npx zen generate

pnpm

pnpm zen generate

bun

bunx zen generate

yarn

npx zen generate

3. Manual setup

You can also always configure a project manually with the following steps:

1. Install dependencies

npm

npm install --save-dev @zenstackhq/cli@next
npm install @zenstackhq/runtime@next

pnpm

pnpm add --save-dev @zenstackhq/cli@next
pnpm add @zenstackhq/runtime@next

bun

bun add --dev @zenstackhq/cli@next
bun add @zenstackhq/runtime@next

yarn

yarn add --dev @zenstackhq/cli@next
yarn add @zenstackhq/runtime@next

2. Create a zenstack/schema.zmodel file

You can use the following sample schema to get started:

datasource db {
  provider = 'sqlite'
  url = "file:./dev.db"
}

model User {
  id       String @id @default(cuid())
  email    String @unique
  posts    Post[]
}

model Post {
  id        String   @id @default(cuid())
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
  title     String
  content   String
  published Boolean  @default(false)
  author    User     @relation(fields: [authorId], references: [id])
  authorId  String
}

3. Run the CLI generate command to compile the schema into TypeScript

npm

npx zen generate

pnpm

pnpm zen generate

bun

bunx zen generate

yarn

npx zen generate

4. Custom schema and output paths

By default, ZenStack CLI loads the schema from zenstack/schema.zmodel. You can change this by passing the --schema option. TypeScript files are by default generated to the same directory as the schema file. You can change this by passing the --output option.

You can choose to either commit the generated TypeScript files to your source control, or add them to .gitignore and generate them on the fly in your CI/CD pipeline.