You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
I want to thank you first for considering contributing to ZenStack 🙏🏻. It's people like you who make ZenStack a better toolkit that benefits more developers!
4
+
5
+
Before you start working on anything major, please make sure to open an issue or discuss with us in our [Discord](https://discord.gg/Ykhr738dUe) first. This will help ensure your work aligns with the project's goals and avoid duplication of effort.
6
+
7
+
## Prerequisites
8
+
9
+
- Node.js: v20 or above
10
+
- PNPM: as specified in [package.json](./package.json)
11
+
12
+
Test cases are run against both SQLite and Postgres. You should have a postgres server (16 or above) running (either natively or via Docker). The default connection is:
The default values for the environment variables (if not set) are:
17
+
18
+
-`TEST_PG_HOST`: localhost
19
+
-`TEST_PG_PORT`: 5432
20
+
-`TEST_PG_USER`: postgres
21
+
-`TEST_PG_PASSWORD`: postgres
22
+
23
+
## Get started
24
+
25
+
1. Install dependencies: `pnpm install`
26
+
2. Build all packages: `pnpm build`
27
+
3. Run all tests: `pnpm test`
28
+
29
+
## Development workflow
30
+
31
+
ZenStack adopts a very simple development workflow:
32
+
33
+
1. Changes should be made in branches created off the "dev" branch.
34
+
35
+
1. Non-trivial changes should include test cases. Bug-fixes should include regression tests that refer to GitHub issues if applicable.
36
+
37
+
1. After coding and testing, create a PR to merge the changes into the "dev" branch.
38
+
39
+
1. After code review is done, maintainer will squash and merge the PR into the "dev" branch.
40
+
41
+
1. Periodically, the "dev" branch is merged back to the "main" branch to create a new release.
42
+
43
+
## Project structure
44
+
45
+
ZenStack is a monorepo consisting of multiple NPM packages managed by [pnpm workspace](https://pnpm.io/workspaces).
46
+
47
+
### Packages
48
+
49
+
The source and tests of ZenStack npm packages reside in the "packages" folder:
50
+
51
+
#### [language](./packages/language)
52
+
53
+
The ZModel language's definition, including its syntax definition and parser/linker implementation. The compiler is implemented with the [Langium](https://github.com/langium/langium) toolkit.
54
+
55
+
#### [cli](./packages/cli)
56
+
57
+
The `zen` CLI and built-in plugins.
58
+
59
+
#### [schema](./packages/schema)
60
+
61
+
The runtime representation of ZModel schema.
62
+
63
+
#### [orm](./packages/orm)
64
+
65
+
The ORM runtime built on top of [Kysely](https://kysely.dev).
66
+
67
+
#### [server](./packages/server)
68
+
69
+
The `server` package implements the automatic CRUD services and contains two main parts:
70
+
71
+
1. Framework-agnostic API handlers: defining input/output format and API routes in a framework-independent way. Currently supports "rpc" and "rest" styles.
72
+
73
+
1. Framework-specific adapters: translating framework-dependent request and response formats.
TanStack Query client for consuming the automatic CRUD services.
78
+
79
+
#### [sdk](./packages/sdk)
80
+
81
+
Utilities for building ZenStack plugins.
82
+
83
+
#### [plugins/policy](./plugins/policy)
84
+
85
+
The access policy plugin implementation.
86
+
87
+
#### [ide/vscode](./packages/ide/vscode)
88
+
89
+
VSCode extension for ZModel.
90
+
91
+
#### [testtools](./packages/testtools)
92
+
93
+
Test utilities.
94
+
95
+
### Tests
96
+
97
+
#### [e2e](./tests/e2e/)
98
+
99
+
End-to-end tests covering essential features (ORM, access policies, etc.).
100
+
101
+
#### [regression](./tests/regression/)
102
+
103
+
Regression tests for previously reported issues.
104
+
105
+
## Testing changed packages locally
106
+
107
+
The [samples](./samples) folder contains sample projects that directly reference the packages in the workspace. Once you make changes to a package and rebuild it, the sample projects will automatically pick up the changes. They are handy for quick manual testing.
108
+
109
+
If you prefer to test against your own project, simply copy the built bundles (from the `dist` folder of each package) to your project's `node_modules` folder to overwrite the installed packages.
> V3 is currently in beta phase and not ready for production use. Feedback and bug reports are greatly appreciated. Please visit this dedicated [discord channel](https://discord.com/channels/1035538056146595961/1352359627525718056) for chat and support.
25
-
26
24
# What's ZenStack
27
25
28
-
> Read full documentation at 👉🏻 https://zenstack.dev/v3.
26
+
> Read full documentation at 👉🏻 https://zenstack.dev/docs.
29
27
30
-
ZenStack is a TypeScript database toolkit for developing full-stack or backend Node.js/Bun applications. It provides a unified data modeling and access solution with the following features:
28
+
ZenStack is a TypeScript database toolkit for developing full-stack or backend Node.js/Bun applications. It provides a unified data modeling and query solution with the following features:
31
29
32
-
-A modern schema-first ORM that's compatible with [Prisma](https://github.com/prisma/prisma)'s schema and API
-🚀 Advanced data modeling patterns like [polymorphism](https://zenstack.dev/docs/orm/polymorphism)
34
+
-🧩 Designed for extensibility and flexibility
35
+
-⚙️ Automatic CRUD web APIs with adapters for popular frameworks
36
+
-🏖️ Automatic [TanStack Query](https://github.com/TanStack/query) hooks for easy CRUD from the frontend
39
37
40
38
# What's New in V3
41
39
42
-
ZenStack V3 is a major rewrite of [V2](https://github.com/zenstackhq/zenstack). The biggest change is V3 doesn't have a runtime dependency to Prisma anymore. Instead of working as a big wrapper of Prisma as in V2, V3 made a bold move and implemented the entire ORM engine using [Kysely](https://github.com/kysely-org/kysely), while keeping the query API fully compatible with Prisma.
43
-
44
-
Please check [this blog post](https://zenstack.dev/blog/next-chapter-1) for why we made this big architectural change decision.
40
+
ZenStack V3 is a major rewrite of [V2](https://github.com/zenstackhq/zenstack). It replaced Prisma ORM with its own ORM engine built on top of [Kysely](https://kysely.dev) while keeping a Prisma-compatible query API. This architecture change brings the level of flexibility that we couldn't imagine in previous versions. Please check [this blog post](https://zenstack.dev/blog/next-chapter-1) for why we made this bold decision.
45
41
46
42
Even without using advanced features, ZenStack offers the following benefits as a drop-in replacement to Prisma:
47
43
48
44
1. Pure TypeScript implementation without any Rust/WASM components.
49
45
2. More TypeScript type inference, less code generation.
50
46
3. Fully-typed query-builder API as a better escape hatch compared to Prisma's [raw queries](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/raw-queries) or [typed SQL](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/typedsql).
51
47
52
-
> Although ZenStack v3's ORM runtime doesn't depend on Prisma anymore (specifically, `@prisma/client`), it still relies on Prisma to handle database migration. See [database migration](https://zenstack.dev/docs/3.x/orm/migration) for more details.
53
-
54
-
# Quick Start
48
+
# Try It Now
55
49
56
-
-[ORM](./samples/orm): A simple example demonstrating ZenStack ORM usage.
57
-
-[Next.js + TanStack Query](./samples/next.js): A full-stack sample demonstrating using TanStack Query to consume ZenStack's automatic CRUD services in a Next.js app.
50
+
[](https://stackblitz.com/~/github.com/zenstackhq/v3-doc-quick-start?file=zenstack%2fschema.zmodel&file=main.ts&view=editor&showSidebar=0&hideNavigation=1&hideExplorer=1)
58
51
59
52
## Installation
60
53
@@ -63,28 +56,58 @@ Even without using advanced features, ZenStack offers the following benefits as
63
56
Use the following command to scaffold a simple TypeScript command line application with ZenStack configured:
64
57
65
58
```bash
66
-
npm create zenstack@next my-project
59
+
npm create zenstack@latest my-project
67
60
```
68
61
69
62
### 2. Setting up an existing project
70
63
71
64
Or, if you have an existing project, use the CLI to initialize it:
72
65
73
66
```bash
74
-
npx @zenstackhq/cli@next init
67
+
npx @zenstackhq/cli@latest init
75
68
```
76
69
77
70
### 3. Setting up manually
78
71
79
72
Alternatively, you can set it up manually:
80
73
81
74
```bash
82
-
npm install -D @zenstackhq/cli@next
83
-
npm install @zenstackhq/orm@next
75
+
npm install -D @zenstackhq/cli
76
+
npm install @zenstackhq/orm
84
77
```
85
78
86
79
Then create a `zenstack` folder and a `schema.zmodel` file in it.
87
80
88
81
# Documentation
89
82
90
-
Please visit the [doc site](https://zenstack.dev/docs/3.x/) for detailed documentation.
0 commit comments