ZenStack

Fullstack TypeScript toolkit that enhances Prisma ORM with flexible Authori...

Authentication / AuthorizationNext.jsSvelte
zenstackhq/zenstackzenstack.dev@zenstackhq/runtime

README

zenstack


What it is


ZenStack is a Node.js/TypeScript toolkit that simplifies the development of a web app's backend. It enhances Prisma ORM with a flexible Authorization layer and auto-generated, type-safe APIs/hooks, unlocking its full potential for full-stack development.

Our goal is to let you save time writing boilerplate code and focus on building real features!

How it works


Read full documentation at 👉🏻 zenstack.dev. Join Discord for feedback and questions.


ZenStack incrementally extends Prisma's power with the following four layers:

1. ZModel - an extended Prisma schema language


ZenStack introduces a data modeling language called "ZModel" - a superset of Prisma schema language. It extended Prisma schema with custom attributes and functions and, based on that, implemented a flexible access control layer around Prisma.

  1. ```ts
  2. // base.zmodel
  3. abstract model Base {
  4.     id String @id
  5.     author User @relation(fields: [authorId], references: [id])
  6.     authorId String

  8.     // 🔐 allow full CRUD by author
  9.     @@allow('all', author == auth())
  10. }
  11. ```

  1. ```ts
  2. // schema.zmodel
  3. import "base"
  4. model Post extends Base {
  5.     title String
  6.     published Boolean @default(false)

  8.     // 🔐 allow logged-in users to read published posts
  9.     @@allow('read', auth() != null && published)
  10. }
  11. ```

The zenstack CLI transpiles the ZModel into a standard Prisma schema, which you can use with the regular Prisma workflows.

2. Runtime enhancements to Prisma client


At runtime, transparent proxies are created around Prisma clients for intercepting queries and mutations to enforce access policies.

  1. ```ts
  2. import { enhance } from '@zenstackhq/runtime';

  4. // a regular Prisma client
  5. const prisma = new PrismaClient();

  7. async function getPosts(userId: string) {
  8.     // create an enhanced Prisma client that has access control enabled
  9.     const enhanced = enhance(prisma, { user: userId });

  11.     // only posts that're visible to the user will be returned
  12.     return enhanced.post.findMany();
  13. }
  14. ```

3. Automatic RESTful APIs through server adapters


Server adapter packages help you wrap an access-control-enabled Prisma client into backend CRUD APIs that can be safely called from the frontend. Here's an example for Next.js:

  1. ```ts
  2. // pages/api/model/[...path].ts

  4. import { requestHandler } from '@zenstackhq/next';
  5. import { enhance } from '@zenstackhq/runtime';
  6. import { getSessionUser } from '@lib/auth';
  7. import { prisma } from '@lib/db';

  9. // Mount Prisma-style APIs: "/api/model/post/findMany", "/api/model/post/create", etc.
  10. // Can be configured to provide standard RESTful APIs (using JSON:API) instead.
  11. export default requestHandler({
  12.     getPrisma: (req, res) => enhance(prisma, { user: getSessionUser(req, res) }),
  13. });
  14. ```

4. Generated client libraries (hooks) for data access


Plugins can generate strong-typed client libraries that talk to the aforementioned APIs. Here's an example for React:

  1. ```tsx
  2. // components/MyPosts.tsx

  4. import { useFindManyPost } from '@lib/hooks';

  6. const MyPosts = () => {
  7.     // list all posts that're visible to the current user, together with their authors
  8.     const { data: posts } = useFindManyPost({
  9.         include: { author: true },
  10.         orderBy: { createdAt: 'desc' },
  11.     });

  13.     return (
  14.         <ul>
  15.             {posts?.map((post) => (
  16.                 <li key={post.id}>
  17.                     {post.title} by {post.author.name}
  18.                 </li>
  19.             ))}
  20.         </ul>
  21.     );
  22. };
  23. ```