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 interactive playground to experience it inside the browser.

Click here to open an interactive playground.

main.ts

import { SqlJsDialect } from '@zenstackhq/kysely-sql-js';
import { ZenStackClient } from '@zenstackhq/runtime';
import initSqlJs from 'sql.js';
import { schema } from './zenstack/schema';

async function main() {
  // initialize sql.js engine
  const SQL = await initSqlJs();

  // create database client with sql.js dialect
  const db = new ZenStackClient(schema, {
    dialect: new SqlJsDialect({ sqlJs: new SQL.Database() }),
  });

  // push schema to the database (`$pushSchema` is for testing only)
  await db.$pushSchema();

  // create a user with some posts
  const user = await db.user.create({
    data: {
      email: 'u1@test.com',
      posts: {
        create: [
          {
            title: 'Post1',
            content: 'My first post',
            published: false,
          },
          {
            title: 'Post2',
            content: 'Just another post',
            published: true,
          },
        ],
      },
    },
    include: { posts: true },
  });

  console.log(user);
}

main();

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

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.

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.