⛩ Zen ⛩

Nest + Prisma + Apollo + Angular 🏮 Full Stack GraphQL Starter Kit

Zen is a starter kit to build web portals as a stateful single-page application. This kit has everything needed for building a customized user experience utilizing only TypeScript & GraphQL. The project has end-to-end typings and this is achieved by combining several code generation packages together.

Specifically, this is an Nx integrated monorepo, utilizing Angular for the frontend, Nest for the backend, and Prisma for the data persistence solution. Apollo is deeply integrated throughout the entire tech stack, enabling for a modern approach to communication between the client and the server via GraphQL.

The project implements a fully featured authentication & authorization system with a minimalistic implementation. This includes a login component, registration component, password change component and a fully featured password reset flow. All of this while only having 1 model within the schema.prisma file, the User model. Guards & directives are also integrated for both RBAC & ABAC authorization schemes and can be used in conjunction. Everything needed for a malleable and robust user management system has been wired up for you.

Key Features

🏡 Nx, Nest, Prisma, Apollo and Angular.
💙 Everything is written in TypeScript, even code generation scripts are written in TypeScript.
🗃️ End-to-end type safety. Code generation is preconfigured and polished to perfection.
📲 100% responsive design.
💻 100% cross-platform. Develop on any OS and deploy to any OS, including mobile.
♾️ Minimal number of concepts required to understand. Unifying as many solutions as possible such that they are isomorphic between the frontend and backend.
🎐 Modern developer conveniences with high quality Visual Studio Code extensions preconfigured for the project.
🧰 Nx Console VSCode extension is the UI for all Nx workspaces. This really helps to simplify the usage of the varying Angular & Nest schematics available in the ecosystem.
❤️ Angular Language Service for VSCode enables sophisticated IDE tooling over all Angular templates.
🚀 Apollo extension for VSCode is preconfigured and enables code completion for gql tags.
🛰️ apollo-angular is our GraphQL client for Angular. This project code generates everything needed so that all queries/mutations are ready for dependency injection within Angular and are strictly typed.
🐈‍⬛ @nestjs/graphql - Schema first is an exceptional way of building GraphQL servers. This project configures and code generates everything needed to create a GraphQL server with end-to-end type safety.
🔵 Pal.js Generator - SDL first to help generate the GraphQL API for Prisma. Pal.js - Select to solve the GraphQL N+1 problem for all queries for free.
🔐 Purpose-built user authentication & authorization modules. Full suite of authorization components, guards & directives for both Angular & Nest to tailor showing/hiding content and accepting/denying requests for a given user.
🧼 Enforced linting and formatting rules to ensure all contributions have predictable structure and clear legibility.
📖 Storybook is integrated to catalogue available components and makes it much simpler for discoverability of reusable components.
💾 Example deployment scripts to Kubernetes and instructions on setting up a local Kubernetes cluster for testing purposes.
⚙️ Feature branches are available to git merge to enable features such as data grids, telemetry, or SocketIO.
🔌 Seamless communication with the API server. Interceptors have been inserted before all client service network calls to automatically handle authorization. This in combination with the end-to-end type safety for all GraphQL requests makes communicating with the server incredibly simple.
🧪 Jest as the testing framework. Clean output for results and extraordinarily versatile with @nx/jest as the test runner.
🎨 Modern responsive components & theme with SASS (.scss) as the CSS transpiler of choice.

🍣 Setup Instructions - GitHub Repo

Requirements

Node v22
Docker or Rancher Desktop

We are utilizing pnpm as our package manager. Though, you can utilize npm if you prefer by running the equivalent npm commands.

# Project setup steps
git clone https://github.com/ZenSoftware/zen.git
cd zen

# Make a copy of the .env file
cp .env.example .env

# Install node modules
pnpm i

# Start the PostgreSQL server
docker-compose up -d

# Run the initial Prisma migration
pnpm prisma:migrate

# Start the Nest API
pnpm start:api

# Start the Angular app at localhost:4200
pnpm start

# Reload Apollo VSCode extension via command palette after the API has started
>Apollo: Reload schema

🥢 GraphQL Features

[x] Nest GraphQL resolvers to Prisma Client.
[x] Apollo GraphQL SDL bindings to Prisma generated via Pal.js CLI! Thank you @AhmedElywa 🎎
[x] PrismaSelect to eliminate overfetching. Queries are delegated to Prisma which solve the GraphQL N+1 problem for free.
[x] Custom npm scripts to code generate the Nest GraphQL api on Prisma schema changes.
[x] @graphql-codegen/typescript-apollo-angular of apollo-angular services to enable simple, type safe access to the GraphQL API within Angular. 🎀 Modern dev tooling configured for the project, allowing for Apollo extension for VS Code to provide auto-completion within gql tags for all .ts files.
[x] An Angular GraphQLModule to simplify the configuration of the ApolloClient to enable/disable the varying ApolloLink features.
- [x] HttpBatchLink for batching several GraphQL requests that occur within a short time interval. This really helps to alleviate network congestion.
- [x] UploadLink to give ApolloClient HTTP multi-part form requests capabilities. Enabling the uploading of files via GraphQLUpload.
- [x] GraphQLWsLink for GraphQL subscriptions over websockets.

🍱 API Authentication, Performance & Scaling

[x] Nest authentication, user registration and login system designed specifically to work for an Angular SPA (single page application). This project provides responsive, "mobile first" interfaces for the standard set of authentication features.
[x] New account component
[x] Login component with remember me option.
[x] Sign in with Google via OpenID Connect.
[x] Forgot password component and full password reset flow.
[x] Password change component for user dashboards.
[x] Nest guards & directives for both RBAC & ABAC authorization schemes. ABAC is implemented with @casl/prisma & @casl/angular. The user's CASL rules are sent from the server to the client and updates the @casl/angular ability. This unifies the permissions across both the server and the client. Fully exploiting CASL's isomorphic capabilities.
[x] Angular route guards and Angular directives to show/hide content depending on the user's roles or CASL abilities.

🍵 Modern Web Components and Responsive UIs

[x] SASS chosen as the CSS transpiler of choice.
[x] Angular Material components & theme.
[x] Mobile first approach to build the framework's core components (login form, etc).
[x] Directly import Bootstrap reset, utilities, & grid features through SASS (.scss) imports and exclude the Bootstrap theme and conflicting component styles. These features are missing from Angular Material and greatly simplify the creation of responsive, mobile first applications.
[x] Bootswatch SASS (.scss) variables integrated for a large assortment of high quality color themes to choose from.

Zen

Install / Use

README