From 2aa0fd2b64c6a0f46f8776c05bbc3731a215b1c8 Mon Sep 17 00:00:00 2001 From: Yiming Cao Date: Tue, 25 Oct 2022 22:25:13 +0800 Subject: [PATCH 1/5] progress --- README.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 179e3af91..2fd137905 100644 --- a/README.md +++ b/README.md @@ -1 +1,19 @@ -

ZenStack

+
+ + + + +

ZenStack

+ + +
+ +## What is ZenStack? + +## Getting started + +## How does it work? + +## Client-side usage + +## Server-side usage From 17a0d929ab457440aa911f9efee469f45d1f201e Mon Sep 17 00:00:00 2001 From: Yiming Cao Date: Wed, 26 Oct 2022 10:31:48 +0800 Subject: [PATCH 2/5] Progress on README --- README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/README.md b/README.md index 2fd137905..98de10a61 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,22 @@ ## What is ZenStack? +ZenStack is a toolkit for simplifying full-stack development with Node.js web frameworks like [Next.js](https://nextjs.org/), [Nuxt.js](https://nuxtjs.org/) and [SvelteKit](https://kit.svelte.dev/) , using Typescript language. + +With the increasing power of such frameworks, it's becoming more and more practical to build a complex web app all within one unified framework. However, you'll still need to spend significantly amout of engergy to design and build up the backend part of your app. + +Things to consider inlcude: + +- What kind of API to use? RESTful or GraphQL? +- How to model your data and map the model to both source code and database (ORM)? +- How to implement common CRUD operations? Manually construct it or use a generator? +- How to evolve your data model? +- How to authenticate users and authorize their requests? + +ZenStack aims to simplify these tasks by providing an intuitive data modeling language to define data types and access policies, integrated with user authentication. It generates RESTful services as well as a client-side library, allowing flexible and painless CRUD operations. Typescript types are generated for data models, CRUD input, filters, etc., so that you get great coding experiences in IDE and have much fewer chances to make mistakes. + +ZenStack is both heavily inspired and built above [Prisma ORM](https://www.prisma.io/), which is IMO the best ORM toolkit in the market. Familarity with Prisma should make it very easy to pick up ZenStack, but it's not prerequisite since the modeling language is intuitive and the development workflow is straightforward. + ## Getting started ## How does it work? @@ -17,3 +33,5 @@ ## Client-side usage ## Server-side usage + +## What's next? From d4318623e77bb2f6397ac8b6062b0c2e2a586545 Mon Sep 17 00:00:00 2001 From: Yiming Cao Date: Wed, 26 Oct 2022 13:23:04 +0800 Subject: [PATCH 3/5] update --- README.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 98de10a61..ba7d30eb1 100644 --- a/README.md +++ b/README.md @@ -24,10 +24,25 @@ Things to consider inlcude: ZenStack aims to simplify these tasks by providing an intuitive data modeling language to define data types and access policies, integrated with user authentication. It generates RESTful services as well as a client-side library, allowing flexible and painless CRUD operations. Typescript types are generated for data models, CRUD input, filters, etc., so that you get great coding experiences in IDE and have much fewer chances to make mistakes. -ZenStack is both heavily inspired and built above [Prisma ORM](https://www.prisma.io/), which is IMO the best ORM toolkit in the market. Familarity with Prisma should make it very easy to pick up ZenStack, but it's not prerequisite since the modeling language is intuitive and the development workflow is straightforward. +ZenStack is both heavily inspired and built above [Prisma ORM](https://www.prisma.io/), which is in our oppinion the best ORM toolkit in the market. Familarity with Prisma should make it very easy to pick up ZenStack, but it's not prerequisite since the modeling language is intuitive and the development workflow is straightforward. ## Getting started +### With Next.js + +The easiest way to start using ZenStack is by creating a new Next.js project from a preconfigured template. + +1. Make sure you have Node.js 16 or above and NPM 6 or above installed +1. + +### With Nuxt.js + +![](https://img.shields.io/badge/-Coming%20Soon-gray) + +### With SvelteKit + +![](https://img.shields.io/badge/-Coming%20Soon-gray) + ## How does it work? ## Client-side usage From 1a53b408bb0e1763ca322caf0722f0a9166be172 Mon Sep 17 00:00:00 2001 From: Yiming Cao Date: Wed, 26 Oct 2022 21:51:42 +0800 Subject: [PATCH 4/5] update readme --- README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 46 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index ba7d30eb1..bf5ea1be3 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ ZenStack is a toolkit for simplifying full-stack development with Node.js web frameworks like [Next.js](https://nextjs.org/), [Nuxt.js](https://nuxtjs.org/) and [SvelteKit](https://kit.svelte.dev/) , using Typescript language. -With the increasing power of such frameworks, it's becoming more and more practical to build a complex web app all within one unified framework. However, you'll still need to spend significantly amout of engergy to design and build up the backend part of your app. +Thanks to the increasing power of frameworks, it's becoming more and more practical to build a complex web app all within one unified framework. However, you'll still need to spend significantly amout of engergy to design and build up the backend part of your app. Things to consider inlcude: @@ -24,24 +24,60 @@ Things to consider inlcude: ZenStack aims to simplify these tasks by providing an intuitive data modeling language to define data types and access policies, integrated with user authentication. It generates RESTful services as well as a client-side library, allowing flexible and painless CRUD operations. Typescript types are generated for data models, CRUD input, filters, etc., so that you get great coding experiences in IDE and have much fewer chances to make mistakes. +Since CRUD APIs are automatically generated with access policies injected, you can implement most of your business logic in your front-end code safely. Read operations never return data that's not supposed to be visible for the current user, and writes will be rejected if unauthorized. The data-access client library also supports nested writes, which allows you to make a batch of creates/updates atomically, eliminating the needs for explicitly using a transaction. + ZenStack is both heavily inspired and built above [Prisma ORM](https://www.prisma.io/), which is in our oppinion the best ORM toolkit in the market. Familarity with Prisma should make it very easy to pick up ZenStack, but it's not prerequisite since the modeling language is intuitive and the development workflow is straightforward. ## Getting started ### With Next.js -The easiest way to start using ZenStack is by creating a new Next.js project from a preconfigured template. +The easiest way to start using ZenStack is by creating a new Next.js project from a preconfigured starter template. + +Here we demonstrate the process with a simple Blog starter using [Next-Auth](https://next-auth.js.org/) for user authentication. + +1. Make sure you have Node.js 16 or above and NPM 8 or above installed + +2. Create a new Next.js project from ZenStack starter + +```bash +npx create-next-app [project name] --use-npm -e https://github.com/zenstackhq/nextjs-auth-starter + +cd [project name] +``` + +3. Run ZenStack generator to generate data services, auth adapter, and the client library + +```bash +npm run generate +``` -1. Make sure you have Node.js 16 or above and NPM 6 or above installed -1. +4. Initialize your local db and creates the first migration + The starter is preconfigured with a local sqlite database. Run the following command to populate its schema and generates a migration history: + +```bash +npm run db:migrate -- -n init +``` + +5. Start the app + +```bash +npm run dev +``` + +If everything worked correctly, you should have a blog site where you can signup, author drafts and publish them. + +You can also try signing up multiple accounts and verify that drafts created by different users are isolated. + +Checkout [the starter's documentation](https://github.com/zenstackhq/nextjs-auth-starter#readme) for more details. ### With Nuxt.js -![](https://img.shields.io/badge/-Coming%20Soon-gray) +![](https://img.shields.io/badge/-Coming%20Soon-lightgray) ### With SvelteKit -![](https://img.shields.io/badge/-Coming%20Soon-gray) +![](https://img.shields.io/badge/-Coming%20Soon-lightgray) ## How does it work? @@ -49,4 +85,8 @@ The easiest way to start using ZenStack is by creating a new Next.js project fro ## Server-side usage +## Development workflow + ## What's next? + +## Reach out to us for any issue, feedback or ideas! From 6040cc191e854f04e262ec99a6fbe11b0c29e27f Mon Sep 17 00:00:00 2001 From: Yiming Cao Date: Wed, 26 Oct 2022 22:29:54 +0800 Subject: [PATCH 5/5] Readme progress --- README.md | 37 ++++++++++++++++++++++++++++++++----- 1 file changed, 32 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index bf5ea1be3..d1d8a7f03 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ ZenStack is a toolkit for simplifying full-stack development with Node.js web fr Thanks to the increasing power of frameworks, it's becoming more and more practical to build a complex web app all within one unified framework. However, you'll still need to spend significantly amout of engergy to design and build up the backend part of your app. -Things to consider inlcude: +Things that make you stressful include: - What kind of API to use? RESTful or GraphQL? - How to model your data and map the model to both source code and database (ORM)? @@ -22,7 +22,11 @@ Things to consider inlcude: - How to evolve your data model? - How to authenticate users and authorize their requests? -ZenStack aims to simplify these tasks by providing an intuitive data modeling language to define data types and access policies, integrated with user authentication. It generates RESTful services as well as a client-side library, allowing flexible and painless CRUD operations. Typescript types are generated for data models, CRUD input, filters, etc., so that you get great coding experiences in IDE and have much fewer chances to make mistakes. +ZenStack aims to simplify these tasks by providing an intuitive data modeling language to define data types and access policies, integrated with user authentication. It maps your data model to a relational database schema, generates RESTful services as well as a client-side library, allowing flexible and painless CRUD operations. + +Typescript types are generated for data models, CRUD input, filters, etc., so that you get great coding experiences in IDE and have much fewer chances to make mistakes. + +![Diagram here] Since CRUD APIs are automatically generated with access policies injected, you can implement most of your business logic in your front-end code safely. Read operations never return data that's not supposed to be visible for the current user, and writes will be rejected if unauthorized. The data-access client library also supports nested writes, which allows you to make a batch of creates/updates atomically, eliminating the needs for explicitly using a transaction. @@ -81,12 +85,35 @@ Checkout [the starter's documentation](https://github.com/zenstackhq/nextjs-auth ## How does it work? -## Client-side usage +ZenStack has four essential responsibilities: + +1. Mapping data model to db schema and program types (ORM) +1. Integrating with authentication +1. Generating CRUD APIs and enforcing data access policy checks +1. Providing type-safe client CRUD library + +We'll briefly go through each of them in this section. + +### ORM + +### Authentication -## Server-side usage +### Data access policy checking + +### Type-safe client library + +## Developing with the generated code + +### Client-side + +### Server-side usage ## Development workflow +## Database considerations + ## What's next? -## Reach out to us for any issue, feedback or ideas! +## Reach out to us for issues, feedback and ideas! + +[Discussions](../discussions) [Issues](../issues) [Discord]() [Twitter]()