ZenStack V2

https://zenstack.dev/docs/2.x
Admin
ZenStack is an open-source TypeScript toolkit built on Prisma that enables rapid development of...
Tokens:144,093
Snippets:1,612
Trust Score:7.8
Update:3 months ago
Show doc for...
Tokens:
Raw
### ZenStack Info Output Example

Source: https://zenstack.dev/docs/2.x/the-complete-guide/part1/cli

Example output of the 'zenstack info' command, showing installed packages and version status.

```text
Installed ZenStack Packages:  
    zenstack                    x.y.z  
    @zenstackhq/runtime         x.y.z  
✔ Checking npm registry  
You are using the latest version of ZenStack.  


```

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

### Create and Run a Nuxt Project

Source: https://zenstack.dev/docs/2.x/quick-start/nuxt

Use degit to copy a Nuxt local auth example, install dependencies, and start the development server.

```bash
npx degit nuxt/examples/examples/auth/local my-nuxt-blog  
cd my-nuxt-blog  
npm install  
npm run dev  
```

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

### Mounting the Hono Adapter

Source: https://zenstack.dev/docs/2.x/reference/server-adapters/hono

This example demonstrates how to install the Hono adapter and mount the API routes onto a Hono application. It includes setting up the Prisma client with ZenStack's enhance API to enforce access policies.

```APIDOC
## Mounting the API

You can use the `createHonoHandler` API to create a Hono middleware that handles CRUD requests automatically:

```typescript
import { PrismaClient } from '@prisma/client';
import { enhance } from '@zenstack/runtime';
import { createHonoHandler } from '@zenstack/server/hono';
import { Context, Hono } from 'hono';

const prisma = new PrismaClient();
const app = new Hono();

app.use(
    '/api/model/*',
    createHonoHandler({
        getPrisma: (ctx) => {
            return enhance(prisma, { user: getCurrentUser(ctx) });
        },
    })
);

function getCurrentUser(ctx: Context) {
    // the implementation depends on your authentication mechanism
    ...
}
```

The middleware factory takes the following options to initialize:

*   `getPrisma` (required)
    > (ctx: Context) => unknown | Promise<unknown>
    A callback for getting a PrismaClient instance for talking to the database. Usually you'll use an enhanced instance created with ZenStack's `enhance` API to ensure access policies are enforced.

*   `logger` (optional)
    > LoggerConfig
    Configuration for customizing logging behavior.

*   `modelMeta` (optional)
    > ModelMeta
    Model metadata. By default loaded from the `node_module/.zenstack/model-meta` module. You can pass it in explicitly if you configured ZenStack to output to a different location. E.g.: `require('output/model-meta').default`.

*   `zodSchemas` (optional)
    > ModelZodSchema | boolean | undefined
    Provides the Zod schemas used for validating CRUD request input. The Zod schemas can be generated with the `@core/zod` plugin. Pass `true` for this option to load the schemas from the default location. If you configured `@core/zod` plugin to output to a custom location, you can load the schemas explicitly and pass the loaded module to this option. E.g.:
    ```typescript
    factory({
        ...
        zodSchemas: require('./zod'),
    });
    ```

    Not passing this option or passing in `undefined` disables input validation.

*   `handler` (optional)
    > (req: RequestContext) => Promise<Response>
    The request handler function. This option determines the API endpoints and its input and output formats. Currently ZenStack supports two styles of APIs: RPC (the default) and RESTful.
    *   RPC
        The goal of the RPC-style API handler is to fully mirror PrismaClient's API across the network, so that developers can continue enjoying the convenience and flexibility of Prisma's query syntax. This is the default choice for the `handler` option.
        The RPC-style handler can be created like:
        ```typescript
        import { RPCApiHandler } from '@zenstack/server/api';
        const handler = RPCApiHandler();
        ```
        For more details, please check out RPC API Handler.
    *   RESTful
        The goal of RESTful-style API handler is to provide a resource-centric RESTful API using JSON:API as transportation format.
        The RESTful-style handler can be created like:
        ```typescript
        import { RestApiHandler } from '@zenstack/server/api';
        const handler = RestApiHandler({ endpoint: 'http://myhost/api' });
        ```
        For more details, please check out RESTful API Handler.
```

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

### Start Development Server

Source: https://zenstack.dev/docs/2.x/the-complete-guide/part4/auth-ui

Command to start the development server for the application.

```bash
npm run dev  

```

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

### Install and Initialize Prisma

Source: https://zenstack.dev/docs/2.x/quick-start/nestjs

Install Prisma as a development dependency and initialize it in your project.

```bash
npm install -D prisma  
npx prisma init  
```

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

### Mounting the API with ZenStackMiddleware

Source: https://zenstack.dev/docs/2.x/reference/server-adapters/express

This example demonstrates how to install ZenStack API routes onto an Express.js project using the ZenStackMiddleware. It shows how to configure the middleware with a `getPrisma` callback to enhance the PrismaClient with user session information for access policy enforcement.

```APIDOC
## Mounting the API

You can integrate ZenStack into your project with the `ZenStackMiddleware` express middleware:

```javascript
import { PrismaClient } from '@prisma/client';
import { enhance } from '@zenstackhq/runtime';
import { ZenStackMiddleware } from '@zenstackhq/server/express';
import express from 'express';

const prisma = new PrismaClient();
const app = express();

app.use(express.json());

app.use(
    '/api/model',
    ZenStackMiddleware({
        // getSessionUser extracts the current session user from the request, its
        // implementation depends on your auth solution
        getPrisma: (request) => enhance(prisma, { user: getSessionUser(request) }),
    })
);
```

The Express.js adapter takes the following options to initialize:

*   `getPrisma` (required)
    > (request: Request, response: Response) => unknown | Promise<unknown>
    A callback for getting a PrismaClient instance for talking to the database. Usually you'll use an enhanced instance created with ZenStack's `enhance` API to ensure access policies are enforced.
*   `logger` (optional)
    > LoggerConfig
    Configuration for customizing logging behavior.
*   `modelMeta` (optional)
    > ModelMeta
    Model metadata. By default loaded from the `node_module/.zenstack/model-meta` module. You can pass it in explicitly if you configured ZenStack to output to a different location. E.g.: `require('output/model-meta').default`.
*   `zodSchemas` (optional)
    > ModelZodSchema | boolean | undefined
    Provides the Zod schemas used for validating CRUD request input. The Zod schemas can be generated with the `@core/zod` plugin. Pass `true` for this option to load the schemas from the default location. If you configured `@core/zod` plugin to output to a custom location, you can load the schemas explicitly and pass the loaded module to this option. E.g.:
    ```javascript
    factory({
        ...
        zodSchemas: require('./zod'),
    });
    ```

    Not passing this option or passing in `undefined` disables input validation.
*   `handler` (optional)
    > (req: RequestContext) => Promise<Response>
    The request handler function. This option determines the API endpoints and its input and output formats. Currently ZenStack supports two styles of APIs: RPC (the default) and RESTful.
    *   RPC
        The goal of the RPC-style API handler is to fully mirror PrismaClient's API across the network, so that developers can continue enjoying the convenience and flexibility of Prisma's query syntax. This is the default choice for the `handler` option.
        The RPC-style handler can be created like:
        ```javascript
        import { RPCApiHandler } from '@zenstackhq/server/api';
        const handler = RPCApiHandler();
        ```

        For more details, please check out RPC API Handler.
    *   RESTful
        The goal of RESTful-style API handler is to provide a resource-centric RESTful API using JSON:API as transportation format.
        The RESTful-style handler can be created like:
        ```javascript
        import { RestApiHandler } from '@zenstackhq/server/api';
        const handler = RestApiHandler({ endpoint: 'http://myhost/api' });
        ```

        For more details, please check out RESTful API Handler.

*   `sendResponse` (optional)
    > boolean
    Controls if the middleware directly sends a response. If set to false, the response is stored in the `res.locals` object and then the middleware calls the `next()` function to pass the control to the next middleware. Subsequent middleware or request handlers need to make sure to send a response.
    Defaults to `true`.
```

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

### Install @zenstackhq/server

Source: https://zenstack.dev/docs/2.x/reference/server-adapters/elysia

Install the necessary ZenStack server package using Bun.

```bash
bun install @zenstackhq/server  

```

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

### Installation

Source: https://zenstack.dev/docs/2.x/reference/plugins/tanstack-query

Install the @zenstackhq/tanstack-query plugin as a development dependency.

```APIDOC
npm install --save-dev @zenstackhq/tanstack-query
```

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

### Initialize and seed the database, start dev server

Source: https://zenstack.dev/docs/2.x/quick-start/backend

Push the Prisma schema to the database, populate it with seed data, and start the development server.

```bash
npx prisma db push  
npx prisma db seed  
npm run dev  
```

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

### Clone ZenStack Complete Guide Sample Project

Source: https://zenstack.dev/docs/2.x/the-complete-guide/part2/conclusion

Clone the sample project repository and check out the 'part2' branch to access the completed code up to this point in the guide.

```bash
git clone --branch part2 https://github.com/zenstackhq/the-complete-guide-sample.git my-todo-app  

```

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

### Example Query Key Computation

Source: https://zenstack.dev/docs/2.x/reference/plugins/swr

Provides a concrete example of a query key for `useFindUniqueUser` with specific arguments, showing the resulting JSON structure.

```json
JSON.stringify({
    prefix: 'zenstack',
    model: 'User',
    operation: 'findUnique',
    args: { where: { id: '1' } },
    flags: { infinite: false }
})

```

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

### Install OpenAPI Plugin and Swagger UI Dependencies

Source: https://zenstack.dev/docs/2.x/the-complete-guide/part3/documentation

Install the @zenstackhq/openapi plugin for schema generation and swagger-ui-express for serving the documentation. Ensure types are installed for TypeScript projects.

```bash
npm install --save-dev @zenstackhq/openapi  
npm install swagger-ui-express  
npm install -D @types/swagger-ui-express  
```

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

### Install OpenAPI Plugin

Source: https://zenstack.dev/docs/2.x/reference/plugins/openapi

Install the OpenAPI plugin as a development dependency.

```bash
npm install --save-dev @zenstackhq/openapi  

```

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

### Install ZenStack Server Adapter

Source: https://zenstack.dev/docs/2.x/quick-start/nestjs

Install the necessary package for ZenStack's NestJS integration. This command installs the latest version of the server adapter.

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

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

### Install Hono Adapter

Source: https://zenstack.dev/docs/2.x/reference/server-adapters/hono

Install the necessary package for the Hono adapter.

```bash
npm install @zenstackhq/server  

```

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

### Setup ZenStack Package in RedwoodJS

Source: https://zenstack.dev/docs/2.x/guides/redwood

Run this command at the root of your RedwoodJS project to install the ZenStack package and begin integration.

```bash
yarn rw setup package @zenstackhq/redwood  
```

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

### ZenStack CLI Info Command

Source: https://zenstack.dev/docs/2.x/reference/cli

Get information about your ZenStack installation and related packages.

```bash
zenstack info [options] [path]  

```

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

### Install @zenstackhq/swr

Source: https://zenstack.dev/docs/2.x/reference/plugins/swr

Install the SWR plugin for ZenStack. Ensure you have swr version 2.0.0 or above installed.

```bash
npm install @zenstackhq/swr  

```

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

### Install @zenstackhq/tanstack-query

Source: https://zenstack.dev/docs/2.x/reference/plugins/tanstack-query

Install the @zenstackhq/tanstack-query package as a development dependency.

```bash
npm install --save-dev @zenstackhq/tanstack-query  

```

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

### Start Development Server

Source: https://zenstack.dev/docs/2.x/quick-start/sveltekit

Command to run the SvelteKit development server. Access the application at http://localhost:5173.

```bash
npm run dev

```

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

### Install ZenStack and React Query Packages

Source: https://zenstack.dev/docs/2.x/quick-start/nextjs

Install the necessary packages for ZenStack server integration, React Query, and ZenStack's TanStack Query adapter.

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

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

### Install @zenstackhq/trpc

Source: https://zenstack.dev/docs/2.x/reference/plugins/trpc

Install the @zenstackhq/trpc plugin as a development dependency.

```bash
npm install --save-dev @zenstackhq/trpc  

```

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

### Install bcryptjs Type Definitions

Source: https://zenstack.dev/docs/2.x/quick-start/nextjs

Install the necessary type definitions for bcryptjs to use with NextAuth credential-based authentication.

```bash
npm install --save @types/bcryptjs  
```

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

### Install bcryptjs Type Definitions

Source: https://zenstack.dev/docs/2.x/quick-start/nextjs-app-router

Install type definitions for bcryptjs to use with NextAuth for password hashing.

```bash
npm install --save @types/bcryptjs  

```

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

### Compile the Project

Source: https://zenstack.dev/docs/2.x/the-complete-guide/part4/prepare-project

Run the build command to compile the project and verify that all configurations and setups are working correctly.

```bash
npm run build  

```

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

### Creating a User Resource

Source: https://zenstack.dev/docs/2.x/reference/server-adapters/api-handlers/rest

Example of creating a new user resource with basic attributes.

```http
POST /user
{
    "data": {
        "type": "user",
        "attributes": {
            "name": "Emily",
            "email": "emily@zenstack.dev"
        }
    }
}

```

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

### Install ZenStack Server Adapter

Source: https://zenstack.dev/docs/2.x/the-complete-guide/part4/prepare-project

Install the `@zenstack/server` package using npm to enable ZenStack's server adapters for mounting CRUD APIs.

```bash
npm install @zenstack/server  

```

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

### Start ZenStack REPL

Source: https://zenstack.dev/docs/2.x/reference/cli

Launches the ZenStack Read-Eval-Print Loop for interactive database operations and schema exploration.

```bash
npx zenstack repl  
```

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

### Example Query Key Computation

Source: https://zenstack.dev/docs/2.x/reference/plugins/tanstack-query

Provides an example of a computed query key for a 'useFindUniqueUser' hook with specific arguments.

```plaintext
['zenstack', 'User', 'findUnique', { where: { id: '1' } }, { infinite: false }]  
```

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

### Generate Schema, Push DB, and Start REPL

Source: https://zenstack.dev/docs/2.x/the-complete-guide/part1/other-enhancements

Commands to regenerate the schema, apply database changes, and start the ZenStack REPL for interactive database operations.

```bash
npx zenstack generate
npx prisma db push
npx zenstack repl
```

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

### Svelte Context Provider Setup (+layout.svelte)

Source: https://zenstack.dev/docs/2.x/reference/plugins/tanstack-query

Configure the Zenstack hooks context in a Svelte application using `setHooksContext`. Includes setup for TanStack Query client.

```svelte
<script lang="ts">
    import { QueryClient, QueryClientProvider } from '@tanstack/svelte-query';
    import { setHooksContext } from '$lib/hooks';
    import type { FetchFn } from '@zenstackhq/tanstack-query/runtime';

    // custom fetch function that adds a custom header
    const myFetch: FetchFn = (url, options) => {
        options = options ?? {};
        options.headers = {
            ...options.headers,
            'x-my-custom-header': 'hello world',
        };
        return fetch(url, options);
    };

    setHooksContext({
        endpoint: '/api/model',
        fetch: myFetch,
    });

    const queryClient = new QueryClient();
</script>

<div>
    <QueryClientProvider client={queryClient}>
        <slot />
    </QueryClientProvider>
</div>
```

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

### Install Zenstack Server and Tanstack Query Packages

Source: https://zenstack.dev/docs/2.x/quick-start/nextjs-app-router

Install the necessary Zenstack and Tanstack Query packages for server-side CRUD operations and React data fetching.

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

```

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

### Install Express and ZenStack Server Dependencies

Source: https://zenstack.dev/docs/2.x/the-complete-guide/part3/server-adapters

Install necessary packages for Express and the ZenStack server adapter. Includes development dependencies for TypeScript execution.

```bash
npm install express @zenstackhq/server  
npm install --save-dev @types/express tsx  
```

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

### Start ZenStack REPL Session

Source: https://zenstack.dev/docs/2.x/reference/cli

Starts an interactive REPL session for testing ZenStack enhanced PrismaClient methods. Ensure you have run `zenstack generate` in the package first.

```bash
npx zenstack repl  

```

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

### Install DaisyUI for Styling

Source: https://zenstack.dev/docs/2.x/the-complete-guide/part4/prepare-project

Installs the daisyUI package as a development dependency. This UI component library works with Tailwind CSS.

```bash
npm i -D daisyui@latest  

```

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

### Install ZenStack Server Adapter for Nuxt.js

Source: https://zenstack.dev/docs/2.x/quick-start/nuxt

Installs the necessary server adapter package for integrating ZenStack with a Nuxt.js application.

```bash
npm install @zenstack/server

```

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

### Install Extra Dependencies

Source: https://zenstack.dev/docs/2.x/quick-start/sveltekit

Add JWT and bcryptjs for authentication-related functionalities, along with their type definitions.

```bash
npm add jsonwebtoken bcryptjs
```

```bash
npm add -D @types/jsonwebtoken @types/bcryptjs
```

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

### Creating a User Resource with Relationships

Source: https://zenstack.dev/docs/2.x/reference/server-adapters/api-handlers/rest

Example of creating a new user resource and attaching an existing post relationship.

```http
POST /user
{
    "data": {
        "type": "user",
        "attributes": {
            "name": "Emily",
            "email": "emily@zenstack.dev"
        },
        "relationships": {
            "posts": {
                "data": [{ "type": "post", "id": 1 }]
            }
        }
    }
}

```

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

### List Installed ZenStack Packages

Source: https://zenstack.dev/docs/2.x/the-complete-guide/part1/cli

Run this command to list all installed ZenStack packages and their versions. It also checks for available updates.

```bash
npx zenstack info  
```

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

### Hashed Password Example

Source: https://zenstack.dev/docs/2.x/the-complete-guide/part1/other-enhancements

Example output from querying a user via the raw Prisma Client, showing the hashed password.

```json
{
  "id": 3,
  "createdAt": "2023-11-09T05:53:28.793Z",
  "updatedAt": "2023-11-09T05:53:28.793Z",
  "email": "ross@zenstack.dev",
  "password": "$2a$12$jYdALEg7gtIi.tc9JmFKuOG3X//0Cdo801xYotdtUw5pXV6Ahb.2m",
  "name": null
}
```

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

### Install Extensions to Enhanced Prisma Client

Source: https://zenstack.dev/docs/2.x/guides/client-extensions

Demonstrates installing client extensions to an already enhanced Prisma Client. This approach is supported since v2.9.0 and yields the same results as extending a base Prisma Client first.

```typescript
const db = enhance(prisma);
const extended = db.$extends({
  model: {
    post: {
      async getFeeds() {
          const context = Prisma.getExtensionContext(this);
          return context.findMany();
      },
    },
  },
});

const feeds = await extended.post.getFeeds();
// `feeds` will only contain published posts

```

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

### Infinite Query Setup with Angular

Source: https://zenstack.dev/docs/2.x/reference/plugins/tanstack-query

Component setup for infinite loading of posts using Tanstack Query in Angular. Requires `useInfiniteFindManyPost` hook.

```typescript
import { CommonModule } from '@angular/common';  
import {  
  ChangeDetectionStrategy,  
  Component,  
  computed,  
  signal,  
} from '@angular/core';  
import { useInfiniteFindManyPost } from '@/lib/hooks';  
  
@Component({  
  selector: 'app-posts-component',  
  standalone: true,  
  imports: [CommonModule],  

```

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

### Example Fetched Data

Source: https://zenstack.dev/docs/2.x/the-complete-guide/part1/access-policy/relations

Sample JSON output representing a fetched 'List' entity.

```json
[
  {
    id: 1,
    createdAt: 2023-11-08T04:38:53.385Z,
    updatedAt: 2023-11-08T04:38:53.385Z,
    spaceId: 1,
    ownerId: 2,
    title: 'Grocery',
    private: false
  }
]
```

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

### Start NestJS Development Server

Source: https://zenstack.dev/docs/2.x/quick-start/nestjs

Run the NestJS application in development mode.

```bash
npm run start:dev  

```

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

### OpenAPI Plugin Configuration

Source: https://zenstack.dev/docs/2.x/reference/plugins/openapi

Example configuration for the OpenAPI plugin.

```APIDOC
### Example

schema.zmodel
```zenstack
datasource db {
    provider = 'sqlite'
    url = 'file:./dev.db'
}

plugin openapi {
    provider = '@zenstackhq/openapi'
    output = './openapi.yaml'
    title = 'My awesome API'
    version = '0.5.0'
    summary = 'Created with ZenStack'
    description = 'My awesome API created with ZenStack'
    prefix = '/api'
}
```
```

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

### ZenStack Generate Output

Source: https://zenstack.dev/docs/2.x/the-complete-guide/part1/cli

Example output from the `zenstack generate` command, showing the progress of various plugins.

```text
⌛️ ZenStack CLI vx.y.z, running plugins  
✔ Generating Prisma schema  
✔ Generating PrismaClient enhancer  
✔ Generating Zod schemas  
  
👻 All plugins completed successfully!  
Don't forget to restart your dev server to let the changes take effect.  
```

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

### Initialize ZenStack Project

Source: https://zenstack.dev/docs/2.x/quick-start/remix-run

Prepare your Remix project for ZenStack by running the init command. This installs dependencies and sets up the schema file.

```bash
npx zenstack@latest init
```

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

### RESTful API Handler Example

Source: https://zenstack.dev/docs/2.x/reference/server-adapters/nestjs

Implement RESTful API handlers using `ApiHandlerService.handleRequest()` with a specified handler and endpoint. This example demonstrates GET and POST requests for a 'post' resource.

```typescript
import { Controller, Get, Post } from '@nestjs/common';  
import { ApiHandlerService } from '@zenstackhq/server/nestjs';  
import RESTApiHandler from '@zenstackhq/server/api/rest';  
  
const ENDPOINT = 'http://localhost';  
  
@Controller('post')  
export class PostController {  
  constructor(private readonly apiHandlerService: ApiHandlerService) {}  
  
  // should align with the route generated by API handler  
  @Get()  
  async list() {  
    return this.apiHandlerService.handleRequest(  
      {  
        handler: RESTApiHandler({  
          endpoint: ENDPOINT,  
        }),  
      }  
    )  
  }  
  
  @Post()  
  async create() {  
    return this.apiHandlerService.handleRequest(  
      {  
        handler: RESTApiHandler({  
          endpoint: ENDPOINT,  
        }),  
      }  
    )  
  }  
}  

```

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

### Control Exposed Endpoints with Next.js Middleware

Source: https://zenstack.dev/docs/2.x/reference/server-adapters/next

Use Next.js middleware to restrict access to specific API endpoints. This example prevents GET requests to the /api/model/user endpoint.

```typescript
import { type NextRequest, NextResponse } from 'next/server';

export function middleware(request: NextRequest) {
    const url = new URL(request.url);
    if (
        request.method === 'GET' &&
        url.pathname.match(/^\/api\/model\/user\/?$/)
    ) {
        return NextResponse.json({ error: 'Not allowed' }, { status: 405 });
    }
}

export const config = {
    matcher: '/api/model/:path*',
};
```

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

### RPC API POST Request Body Format

Source: https://zenstack.dev/docs/2.x/reference/server-adapters/api-handlers/rpc

For HTTP verbs other than GET and DELETE, the query body is sent as `application/json` in the request body. This example demonstrates a `create` operation.

```http
POST /api/post/create  
{ "data": { "title": "Hello World" } }
```

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

### Example API Requests with cURL

Source: https://zenstack.dev/docs/2.x/quick-start/nestjs

Demonstrate creating a user, adding posts, and retrieving all posts using cURL commands.

```bash
curl -X POST -H "Content-Type: application/json" -d '{"name": "Joey"}' localhost:3000/users  
curl -X POST -H "Content-Type: application/json" -d '{"title": "My first post", "authorId": 1}' localhost:3000/posts  
curl -X POST -H "Content-Type: application/json" -d '{"title": "My second post", "authorId": 1}' localhost:3000/posts  
curl localhost:3000/posts  

```

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

### RPC API GET/DELETE Query Parameter Format

Source: https://zenstack.dev/docs/2.x/reference/server-adapters/api-handlers/rpc

For GET and DELETE requests, the query body is serialized and passed as the `q` query parameter. This example shows how to format a `findMany` query.

```http
GET /api/post/findMany?q=%7B%22where%22%3A%7B%22public%22%3Atrue%7D%7D  

  * Endpoint: /api/post/findMany
  * Query parameters: `q` -> `{ "where" : { "public": true } }`
```

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

### Adding a Read Policy to User Model

Source: https://zenstack.dev/docs/2.x/the-complete-guide/part1/access-policy/model-level

This example demonstrates adding a read policy to the User model using the `startsWith` attribute function. Rerun generation and start the REPL to test the policy.

```prisma
model User {
    ... 

    @@allow('read', startsWith(email, 'joey'))
}

```

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

### Initialize ZenStack Project (Custom)

Source: https://zenstack.dev/docs/2.x/reference/cli

Initializes the 'myapp' folder with a specific package manager ('pnpm') and schema location.

```bash
npx zenstack init -p pnpm --prisma prisma/my.schema myapp  

```

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

### Generate and Run ZenStack CLI Commands

Source: https://zenstack.dev/docs/2.x/the-complete-guide/part1/access-policy/relations

Commands to generate the ZenStack application code and start the interactive REPL for testing.

```bash
npx zenstack generate
npx zenstack repl
```

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

### Initialize tRPC Project with ZenStack CLI

Source: https://zenstack.dev/docs/2.x/guides/trpc

Run this command to set up your project with necessary ZenStack and Prisma configurations.

```bash
npx zenstack@latest init  

```

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

### Install ZenStack CLI with npm

Source: https://zenstack.dev/docs/2.x/install

Manually install the ZenStack CLI package as a dev dependency using npm. This is part of the manual installation process.

```bash
npm install --save-dev zenstack@latest  
```

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

### Clone Sample Project

Source: https://zenstack.dev/docs/2.x/the-complete-guide/part3

Clone the sample project repository and check out the 'part2' branch to use as a starting point for the Todo project.

```bash
git clone --branch part2 https://github.com/zenstackhq/the-complete-guide-sample.git my-todo-app  
```

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

### Initialize ZenStack Project (Default)

Source: https://zenstack.dev/docs/2.x/reference/cli

Initializes the current folder for ZenStack with default settings.

```bash
npx zenstack init  

```

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

### Create and Navigate to a New Project

Source: https://zenstack.dev/docs/2.x/the-complete-guide/part1/cli

Use 'try-prisma' to scaffold a new TypeScript CLI project and then navigate into its directory.

```bash
npx try-prisma@latest -n my-todo-app -t orm/script --install npm  
cd my-todo-app  
```

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

### Clone ZenStack Sample Project

Source: https://zenstack.dev/docs/2.x/the-complete-guide/part1/conclusion

Clone the completed sample project for Part 1 of the guide from GitHub. Use this command to check out the 'part1' branch.

```bash
git clone --branch part1 https://github.com/zenstackhq/the-complete-guide-sample.git my-todo-app  
```

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

### ZenStack CLI Init Command

Source: https://zenstack.dev/docs/2.x/reference/cli

Initializes an existing project to use ZenStack. Specify a path to initialize a specific folder.

```bash
zenstack init [options] [path]  

```

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

### Install TanStack Query Dependencies

Source: https://zenstack.dev/docs/2.x/the-complete-guide/part4/generate-hooks

Install the necessary packages for TanStack Query integration with ZenStack.

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

```

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

### Install nestjs-cls Package

Source: https://zenstack.dev/docs/2.x/quick-start/nestjs

Install the nestjs-cls package to manage context within NestJS applications.

```bash
npm install nestjs-cls  
```

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

### Initialize Prisma Adapter for Lucia Auth

Source: https://zenstack.dev/docs/2.x/quick-start/authentication/lucia

Set up the Prisma adapter for Lucia Auth using the `@lucia-auth/adapter-prisma` package. This adapter connects Lucia to your database via Prisma.

```typescript
import { PrismaAdapter } from "@lucia-auth/adapter-prisma";
import { PrismaClient } from "@prisma/client";

const client = new PrismaClient();

const adapter = new PrismaAdapter(client.session, client.user);
```

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

### Install tRPC Package for ZenStack

Source: https://zenstack.dev/docs/2.x/guides/trpc

Install the tRPC package as a development dependency to enable router generation.

```bash
npm install -D @zenstackhq/trpc@latest  

```

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

### Set Up Context Providers for React Query and NextAuth

Source: https://zenstack.dev/docs/2.x/quick-start/nextjs-app-router

Create this file to set up `QueryClientProvider` for React Query and `SessionProvider` for NextAuth. This is required for both libraries to function correctly within the app.

```typescript
"use client";  
  
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";  
import { SessionProvider } from "next-auth/react";  
import type { ReactNode } from "react";  
  
const queryClient = new QueryClient();  
  
export default function Providers({ children }: { children: ReactNode }) {  
  return (  
    <QueryClientProvider client={queryClient}>  
      <SessionProvider>{children}</SessionProvider>  
    </QueryClientProvider>  
  );  
}  

```

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

### Example Generated tRPC Router Code

Source: https://zenstack.dev/docs/2.x/guides/trpc

This is an example of the tRPC router code automatically generated by ZenStack.

```typescript
import { createTRPCRouter } from "../../trpc";
import { procedure } from "../../trpc";

export default function createRouter() {
  return createTRPCRouter({
    findMany: procedure.input(...).query(...) => ...
    ...
  });
}


```

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

### Initialize ZenStack CLI for Prisma Migration

Source: https://zenstack.dev/docs/2.x/guides/existing-prisma

Run this command to automatically convert your existing Prisma project to ZenStack. It copies the schema and installs necessary packages.

```bash
npx zenstack@latest init  
```

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

### Create Basic Express App

Source: https://zenstack.dev/docs/2.x/the-complete-guide/part3/server-adapters

Set up a simple Express server with JSON middleware and a basic root route. Used for initial verification before integrating ZenStack.

```typescript
import express from 'express';  
  
const app = express();  
  
app.use(express.json());  
  
app.get('/', (req, res) => {  
    res.json({ greet: 'Hello World!' });  
});  
  
app.listen(3000, () => console.log('🚀 Server ready at: http://localhost:3000'));  
```

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

### Install TanStack Query Plugin for Nuxt.js

Source: https://zenstack.dev/docs/2.x/quick-start/nuxt

Installs the TanStack Query plugin package and its Vue query dependency for generating client hooks.

```bash
npm install @zenstack/tanstack-query @tanstack/vue-query

```

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

### Install ZenStack Runtime with npm

Source: https://zenstack.dev/docs/2.x/install

Manually install the @zenstackhq/runtime package as a regular dependency using npm. This package is required for runtime enhancements.

```bash
npm install @zenstackhq/runtime@latest  
```

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

### Clone Completed Sample Project

Source: https://zenstack.dev/docs/2.x/the-complete-guide/part3/conclusion

Clone the repository and checkout the 'part3' branch to access the completed sample project for this section.

```bash
git clone --branch part3 https://github.com/zenstackhq/the-complete-guide-sample.git my-todo-app  

```

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

### Example ZenStack Debug Output

Source: https://zenstack.dev/docs/2.x/the-complete-guide/part1/debugging

This is an example of the Prisma query logs you might see in the console when debugging ZenStack operations, showing the generated query structure.

```json
prisma:info [policy] `findMany` list:  
{
  where: { 
    AND: [
      { NOT: { OR: [] } },
      {
        OR: [
          { owner: { is: { id: 1 } } },
          {
            AND: [
              {
                space: {
                  members: {
                    some: { user: { is: { id: 1 } } }
                  }
                }
              },
              { NOT: { private: true } }
            ]
          }
        ]
      }
    ]
  }
}


```

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

### Create New SvelteKit Project

Source: https://zenstack.dev/docs/2.x/quick-start/sveltekit

Use npm to create a new SvelteKit project with TypeScript, ESLint, and Prettier.

```bash
npm create svelte@latest my-blog-app
```

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

### ZenStack CLI Usage

Source: https://zenstack.dev/docs/2.x/reference/cli

Basic usage of the ZenStack CLI. Use `zenstack --help` for a full list of commands and options.

```bash
zenstack [options] [command]  
  
ζ ZenStack is a Prisma power pack for building full-stack apps.  
  
Documentation: https://zenstack.dev.  
  
Options:  
  -v --version           display CLI version  
  -h, --help             display help for command  
  
Commands:  
  info [path]            Get information of installed ZenStack and related packages.  
  init [options] [path]  Initialize an existing project for ZenStack.  
  generate [options]     Generates RESTful API and Typescript client for your data model.  
  repl [options]         Start a REPL session.  
  format [options]       Format a ZenStack schema file.  
  check [options]        Check a ZenStack schema file for syntax or semantic errors.  
  help [command]         Display help for a command.  

```

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

### Install Nanoid for Unique IDs

Source: https://zenstack.dev/docs/2.x/the-complete-guide/part4/prepare-project

Installs the 'nanoid' package, a library for generating unique IDs. This is a utility package that may be used for various purposes within the application.

```bash
npm install nanoid

```

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

### Create User and Attach Posts via RESTful Handler

Source: https://zenstack.dev/docs/2.x/reference/server-adapters/sveltekit

This example demonstrates creating a user and then attaching existing posts using a POST request to a RESTful API handler. It follows the JSON:API specification for the request body.

```javascript
// create a user and attach two posts  
const r = await fetch(`/api/user`, {  
    method: 'POST',  
    headers: { 'Content-Type': 'application/vnd.api+json' },  
    body: JSON.stringify({  
        data: {  
            type: 'user',  
            attributes: {  
                email: 'user1@abc.com'  
            },  
            relationships: {  
                posts: {  
                    data: [  
                        { type: 'post', id: 1 },  
                        { type: 'post', id: 2 }  
                    ]  
                }  
            }  
        }  
    })  
});  
  
console.log(await r.json());  

```

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

### Example ZenStack Debug Log Output

Source: https://zenstack.dev/docs/2.x/guides/debugging

This is an example of the detailed Prisma query logged by ZenStack when debug logging is enabled. It shows the policy-injected `where` clause for a `findMany` operation.

```json
prisma:info [policy] `findMany` list:  
{
  where: {
    AND: [
      { NOT: { OR: [] } },
      {
        OR: [
          { owner: { is: { id: 1 } } },
          {
            AND: [
              {
                space: {
                  members: {
                    some: { user: { is: { id: 1 } } }
                  }
                }
              },
              { NOT: { private: true } }
            ]
          }
        ]
      }
    ]
  }
}


```

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

### Create a new Prisma project with Express.js

Source: https://zenstack.dev/docs/2.x/quick-start/backend

Use the try-prisma CLI to generate a new Express.js project. This sets up the basic structure for your backend application.

```bash
npx try-prisma@latest -t orm/express -n my-blog-app  
cd my-blog-app  
npm install  
```

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

### Specify Package Manager for ZenStack Installation

Source: https://zenstack.dev/docs/2.x/guides/existing-prisma

Explicitly set the package manager (npm, pnpm, or yarn) for installing ZenStack and its runtime dependencies using the --package-manager option.

```bash
npx zenstack@latest init --package-manager pnpm  
```

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

### TRPC App Router Setup with Generated Routers

Source: https://zenstack.dev/docs/2.x/reference/plugins/trpc

Integrate ZenStack's generated routers into your tRPC application. This setup uses `createCRUDRouter` and initializes tRPC with custom context.

```typescript
import { createRouter as createCRUDRouter } from './generated/routers';
import { initTRPC } from '@trpc/server';
import { type Context } from '../context';

const t = initTRPC.context<Context>().create();

export const appRouter = createCRUDRouter(t.router, t.procedure);
export type AppRouter = typeof appRouter;
```

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

### Generate Prisma Client and Push Schema

Source: https://zenstack.dev/docs/2.x/quick-start/nestjs

Generate the PrismaClient and apply the schema to your database.

```bash
npx prisma generate  
npx prisma db push  
```
Tokens:
Raw