ZenStack

https://github.com/zenstackhq/zenstack
Admin
ZenStack is a TypeScript database toolkit for full-stack and backend Node.js/Bun applications that...
Tokens:5,530
Snippets:103
Trust Score:8.2
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Start development server

Source: https://github.com/zenstackhq/zenstack/blob/dev/samples/sveltekit/README.md

Run the development server after installing dependencies. Use the --open flag to automatically launch the app in a browser.

```sh
npm run dev

# or start the server and open the app in a new browser tab
npx run dev -- --open
```

--------------------------------

### Install @zenstackhq/fetch-client

Source: https://github.com/zenstackhq/zenstack/blob/dev/packages/clients/fetch-client/README.md

Install the package using npm.

```bash
npm install @zenstackhq/fetch-client
```

--------------------------------

### Install the plugin

Source: https://github.com/zenstackhq/zenstack/blob/dev/packages/plugins/soft-delete/README.md

Install the package via npm.

```bash
npm install @zenstackhq/plugin-soft-delete
```

--------------------------------

### Manual installation

Source: https://github.com/zenstackhq/zenstack/blob/dev/README.md

Install the required ZenStack packages manually to set up the environment.

```bash
npm install -D @zenstackhq/cli
npm install @zenstackhq/schema @zenstackhq/orm
```

--------------------------------

### Install @zenstackhq/server

Source: https://github.com/zenstackhq/zenstack/blob/dev/packages/server/README.md

Install the package using npm.

```bash
npm install @zenstackhq/server
```

--------------------------------

### Initialize TaskForge Project

Source: https://github.com/zenstackhq/zenstack/blob/dev/samples/taskforge/README.md

Commands to install dependencies, generate the ZenStack client, sync the database, seed data, and run the CLI.

```bash
pnpm install          # native builds (better-sqlite3, prisma) are pre-approved in package.json
pnpm zen:generate     # compile zenstack/schema.zmodel -> zenstack/schema.ts (the typed client)
pnpm db:push          # create/sync the SQLite database (zenstack/taskforge.db)
pnpm seed             # populate a demo workspace (users via Better-Auth, domain via the ORM)
pnpm cli orgs         # try the CLI
```

--------------------------------

### Start development server

Source: https://github.com/zenstackhq/zenstack/blob/dev/samples/nuxt/README.md

Launches the Nuxt development server at http://localhost:3302.

```bash
pnpm dev
```

--------------------------------

### Install ZenStack Better-Auth Adapter

Source: https://github.com/zenstackhq/zenstack/blob/dev/packages/auth-adapters/better-auth/README.md

Install the required package using npm.

```bash
npm install @zenstackhq/better-auth@next
```

--------------------------------

### Install @zenstackhq/sdk

Source: https://github.com/zenstackhq/zenstack/blob/dev/packages/sdk/README.md

Use this command to install the SDK package via npm.

```bash
npm install @zenstackhq/sdk
```

--------------------------------

### Install @zenstackhq/orm

Source: https://github.com/zenstackhq/zenstack/blob/dev/packages/orm/README.md

Use npm to install the core ORM package.

```bash
npm install @zenstackhq/orm
```

--------------------------------

### Install project dependencies

Source: https://github.com/zenstackhq/zenstack/blob/dev/samples/nuxt/README.md

Run this command to install all required packages for the Nuxt project.

```bash
pnpm install
```

--------------------------------

### Install ZenStack CLI

Source: https://github.com/zenstackhq/zenstack/blob/dev/packages/cli/README.md

Install the ZenStack CLI as a development dependency in your project.

```bash
npm install -D @zenstackhq/cli
```

--------------------------------

### Install TanStack Query integration

Source: https://github.com/zenstackhq/zenstack/blob/dev/packages/clients/tanstack-query/README.md

Install the required ZenStack package along with the specific TanStack Query adapter for your framework.

```bash
npm install @zenstackhq/tanstack-query @tanstack/react-query
```

--------------------------------

### Install @zenstackhq/schema

Source: https://github.com/zenstackhq/zenstack/blob/dev/packages/schema/README.md

Use npm to add the package to your project dependencies.

```bash
npm install @zenstackhq/schema
```

--------------------------------

### Install the plugin on the client

Source: https://github.com/zenstackhq/zenstack/blob/dev/packages/plugins/soft-delete/README.md

Register the plugin with the ZenStack client at runtime to enable the soft delete behavior.

```typescript
import { ZenStackClient } from '@zenstackhq/orm';
import { SoftDeletePlugin } from '@zenstackhq/plugin-soft-delete';
import { schema } from './schema';

const db = new ZenStackClient(schema, { ... }).$use(new SoftDeletePlugin());

const user = await db.user.create({ data: { email: 'a@example.com' } });

// rewritten to set `deletedAt`, the row is kept in the database
await db.user.delete({ where: { id: user.id } });

// returns `null` — soft-deleted rows are hidden from reads
await db.user.findUnique({ where: { id: user.id } });
```

--------------------------------

### Install @zenstackhq/zod package

Source: https://github.com/zenstackhq/zenstack/blob/dev/packages/zod/README.md

Use this command to add the @zenstackhq/zod dependency to your project.

```bash
npm install @zenstackhq/zod
```

--------------------------------

### Configure file associations for ZenStack extensions

Source: https://github.com/zenstackhq/zenstack/blob/dev/packages/ide/vscode/README.md

Use these settings in .vscode/settings.json to specify which extension handles .zmodel files when both v2 and v3 are installed.

```json
"files.associations": {
    "*.zmodel": "zmodel-v3"
},
```

```json
"files.associations": {
    "*.zmodel": "zmodel"
},
```

--------------------------------

### Initialize an existing project

Source: https://github.com/zenstackhq/zenstack/blob/dev/README.md

Use the CLI to add ZenStack configuration to an existing project.

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

--------------------------------

### Create a SvelteKit project

Source: https://github.com/zenstackhq/zenstack/blob/dev/samples/sveltekit/README.md

Use these commands to initialize a new SvelteKit project in the current directory or a specific folder.

```sh
# create a new project in the current directory
npx sv create

# create a new project in my-app
npx sv create my-app
```

--------------------------------

### Initialize database and seed data

Source: https://github.com/zenstackhq/zenstack/blob/dev/samples/nuxt/README.md

Prepares the database schema and populates it with initial data.

```bash
pnpm db:init
```

--------------------------------

### Initialize a new ZenStack project

Source: https://github.com/zenstackhq/zenstack/blob/dev/packages/create-zenstack/README.md

Run this command in your terminal to scaffold a new project named 'my-app' with ZenStack pre-configured.

```bash
npm create zenstack@latest my-app
```

--------------------------------

### Build and preview production

Source: https://github.com/zenstackhq/zenstack/blob/dev/samples/sveltekit/README.md

Commands to generate a production-ready build and preview it locally.

```sh
npm run build
```

```sh
npm run preview
```

--------------------------------

### Build and Development Commands

Source: https://github.com/zenstackhq/zenstack/blob/dev/CLAUDE.md

Standard commands for building, watching, linting, and testing the ZenStack monorepo.

```bash
pnpm build
```

```bash
pnpm watch
```

```bash
pnpm lint
```

```bash
pnpm test
```

--------------------------------

### Initialize ZenStack Client

Source: https://github.com/zenstackhq/zenstack/blob/dev/samples/orm/README.md

Create a database client instance using the generated TypeScript schema and a Kysely dialect.

```ts
import { ZenStackClient } from '@zenstackhq/orm';
import { schema } from './zenstack/schema';
import SQLite from 'better-sqlite3';
import { SqliteDialect } from 'kysely';

const db = ZenStackClient(schema, {
    dialect: new SqliteDialect({ database: new SQLite('./zenstack/dev.db') }),
});
```

--------------------------------

### Initialize and Use Fetch Client

Source: https://github.com/zenstackhq/zenstack/blob/dev/packages/clients/fetch-client/README.md

Create a client instance with a schema and endpoint, then perform CRUD operations or transactions.

```typescript
import { createClient } from '@zenstackhq/fetch-client';
import { schema } from './schema';

const client = createClient(schema, {
    endpoint: 'https://example.com/api/model',
});

const users = await client.user.findMany({ where: { active: true } });
const post = await client.post.create({ data: { title: 'Hello' } });

const [user, newPost] = await client.$transaction([
    { model: 'User', op: 'create', args: { data: { email: 'alice@example.com' } } },
    { model: 'Post', op: 'create', args: { data: { title: 'Hello' } } },
]);
```

--------------------------------

### Initialize and use ZenStackClient

Source: https://github.com/zenstackhq/zenstack/blob/dev/packages/orm/README.md

Import the client, configure the dialect, and perform CRUD operations.

```typescript
import { ZenStackClient } from '@zenstackhq/orm';
import schema from './schema';

const client = new ZenStackClient(schema, {
    /* dialect config */
});

const user = await client.user.findFirst({ where: { email: 'alice@example.com' } });
```

--------------------------------

### Scaffold a new project

Source: https://github.com/zenstackhq/zenstack/blob/dev/README.md

Use this command to create a new TypeScript CLI application with ZenStack pre-configured.

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

--------------------------------

### Configure Better-Auth with ZenStack Adapter

Source: https://github.com/zenstackhq/zenstack/blob/dev/packages/auth-adapters/better-auth/README.md

Initialize the better-auth instance using the zenstackAdapter with your database client.

```typescript
import { zenstackAdapter } from '@zenstackhq/better-auth';

// ZenStack ORM client
import { db } from './db';

const auth = new BetterAuth({
    database: zenstackAdapter(db, {
        provider: 'postgresql', // or 'sqlite'
    }),
    // other better-auth options...
});
```

--------------------------------

### ZenStack CLI Commands

Source: https://github.com/zenstackhq/zenstack/blob/dev/CLAUDE.md

Commands for managing ZenStack projects, schema generation, and database migrations.

```bash
npx zenstack init
```

```bash
npx zenstack generate
```

```bash
npx zenstack db push
```

```bash
npx zenstack migrate dev
```

```bash
npx zenstack migrate deploy
```

--------------------------------

### Declare the plugin in ZModel

Source: https://github.com/zenstackhq/zenstack/blob/dev/packages/plugins/soft-delete/README.md

Add the plugin configuration to your ZModel schema file.

```zmodel
plugin softDelete {
    provider = '@zenstackhq/plugin-soft-delete'
}
```

--------------------------------

### Generate Better-Auth Schema

Source: https://github.com/zenstackhq/zenstack/blob/dev/packages/auth-adapters/better-auth/README.md

Use the better-auth CLI to populate data models into your ZModel schema.

```bash
npx @better-auth/cli generate
```

--------------------------------

### Configure Prettier for zmodel-v3

Source: https://github.com/zenstackhq/zenstack/blob/dev/packages/ide/vscode/README.md

Set the default formatter for zmodel-v3 files to the ZenStack V3 extension in .vscode/settings.json.

```json
"[zmodel-v3]": {
    "editor.defaultFormatter": "zenstack.zenstack-v3"
},
```

--------------------------------

### TaskForge CLI Commands

Source: https://github.com/zenstackhq/zenstack/blob/dev/samples/taskforge/README.md

Common CLI operations for managing organizations, projects, issues, and user authentication.

```bash
pnpm cli orgs                                  # organizations + member/team/project counts
pnpm cli projects [orgSlug]                    # projects + open-issue count (computed field)
pnpm cli issues <projectSlug> [--status S]     # issues + comment count (computed field)
pnpm cli issue <projectSlug> <number>          # deep read: comments, polymorphic attachments, watchers
pnpm cli stats                                 # groupBy + aggregate over issues and invoices
pnpm cli add-issue <projectSlug> <title...>    # auto-numbered create inside a $transaction
pnpm cli signup <email> <name...>              # register a user through Better-Auth
pnpm cli activity [-n N]                        # recent activity-log entries
```

--------------------------------

### Use generated hooks in React

Source: https://github.com/zenstackhq/zenstack/blob/dev/packages/clients/tanstack-query/README.md

Initialize the client with your schema and use the generated hooks for data fetching and mutations.

```tsx
import { useClientQueries } from '@zenstackhq/tanstack-query/react';
import { schema } from './schema';

function PostList() {
    const client = useClientQueries(schema);

    const { data: posts } = client.post.useQuery({
        where: { published: true },
        include: { author: true },
    });

    const { mutate: createPost } = client.post.useMutation();

    return <ul>{posts?.map((p) => <li key={p.id}>{p.title}</li>)}</ul>;
}
```

--------------------------------

### Enable automatic formatting on save

Source: https://github.com/zenstackhq/zenstack/blob/dev/packages/ide/vscode/README.md

Add this setting to .vscode/settings.json to trigger formatting whenever a file is saved.

```json
"editor.formatOnSave": true
```

--------------------------------

### Express Middleware Integration

Source: https://github.com/zenstackhq/zenstack/blob/dev/packages/server/README.md

Configure the ZenStack middleware within an Express application.

```typescript
import express from 'express';
import { ZenStackMiddleware } from '@zenstackhq/server/express';
import { RPCApiHandler } from '@zenstackhq/server/api';

const app = express();
app.use('/api/model', ZenStackMiddleware({...}));
```

--------------------------------

### Execute Complex Queries with Kysely Expression Builder

Source: https://github.com/zenstackhq/zenstack/blob/dev/samples/orm/README.md

Use the $expr key within a where clause to integrate Kysely expression builders into standard queries.

```ts
db.user.findMany({
    where: {
        role: 'USER',
        // `eb` is Kysely expression builder, fully typed
        $expr: (eb) => eb('email', 'like', '%@zenstack.dev'),
    },
});
```

--------------------------------

### Implement Computed Fields

Source: https://github.com/zenstackhq/zenstack/blob/dev/samples/orm/README.md

Provide implementation logic for computed fields during client creation using Kysely expression builders.

```ts
import { createClient } from '@zenstackhq/orm';

const db = createClient({
    computedFields: {
        User: {
            emailDomain: (eb) =>
                // build SQL expression: substr(email, instr(email, '@') + 1)
                eb.fn('substr', [eb.ref('email'), eb(eb.fn('instr', [eb.ref('email'), eb.val('@')]), '+', 1)]),
        },
    },
});
```

--------------------------------

### Mark fields with @deletedAt

Source: https://github.com/zenstackhq/zenstack/blob/dev/packages/plugins/soft-delete/README.md

Define a nullable DateTime field with the @deletedAt attribute in your models.

```zmodel
model User {
    id        Int       @id @default(autoincrement())
    email     String    @unique
    posts     Post[]
    deletedAt DateTime? @deletedAt
}

model Post {
    id        Int       @id @default(autoincrement())
    title     String
    author    User      @relation(fields: [authorId], references: [id])
    authorId  Int
    deletedAt DateTime? @deletedAt
}
```

--------------------------------

### Define Computed Fields in ZModel

Source: https://github.com/zenstackhq/zenstack/blob/dev/samples/orm/README.md

Declare computed fields in the ZModel schema using the @computed attribute.

```prisma
model User {
    ...
    /// Domain of the email address
    emailDomain String @computed
}
```

--------------------------------

### Filter and Sort on Computed Fields

Source: https://github.com/zenstackhq/zenstack/blob/dev/samples/orm/README.md

Use computed fields directly in query filters or sorting operations.

```ts
db.user.findMany({
    where: {
        emailDomain: 'zenstack.dev',
    },
});
```
Tokens:
Raw