Quick Start

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 my-project

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

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 @zenstackhq/cli init

pnpm

pnpm --package=@zenstackhq/cli dlx zen init

bun

bunx @zenstackhq/cli init

yarn

npx @zenstackhq/cli 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. Optionally, run zen db push to push the schema to the database.

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 @zenstackhq/orm
npm install --save-dev @zenstackhq/cli

pnpm

pnpm add @zenstackhq/orm
pnpm add --save-dev @zenstackhq/cli

bun

bun add @zenstackhq/orm
bun add --dev @zenstackhq/cli

yarn

yarn add @zenstackhq/orm
yarn add --dev @zenstackhq/cli

1. 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

info

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. The default settings can also be changed as explained in the CLI reference.

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