⛩ 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 v20
• 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

• Nest GraphQL resolvers to Prisma Client.
• Apollo GraphQL SDL bindings to Prisma generated via Pal.js CLI! Thank you @AhmedElywa 🎎
• PrismaSelect to eliminate overfetching. Queries are delegated to Prisma which solve the GraphQL N+1 problem for free.
• Custom npm scripts to code generate the Nest GraphQL api on Prisma schema changes.
• @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.
• An Angular GraphQLModule to simplify the configuration of the ApolloClient to enable/disable the varying ApolloLink features.
  • HttpBatchLink for batching several GraphQL requests that occur within a short time interval. This really helps to alleviate network congestion.
  • UploadLink to give ApolloClient HTTP multi-part form requests capabilities. Enabling the uploading of files via GraphQLUpload.
  • GraphQLWsLink for GraphQL subscriptions over websockets.

---

🍱 API Authentication, Performance & Scaling

• 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.
• New account component
• Login component with remember me option.
• Sign in with Google via OpenID Connect.
• Forgot password component and full password reset flow.
• Password change component for user dashboards.
• 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.
• 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

• SASS chosen as the CSS transpiler of choice.
• Angular Material components & theme.
• Mobile first approach to build the framework's core components (login form, etc).
• 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.
• Bootswatch SASS (.scss) variables integrated for a large assortment of high quality color themes to choose from.

---

🎏 Optional Tech Integrations

• Electron branch with new npm script start:electron to launch the app within Electron.
• Capacitor branch.
• SocketIO branch demonstrates how to implement a Nest WebSocket Gateway with user authentication.
• Kendo UI branch - which includes @zen/grid. <zen-grid> renders robust and reliable data grids over all of the Prisma models within the project, with minimal configuration needed.
• OpenTelemetry branch demonstrates how to integrate and expose telemetry data for the API server.
• HTML canvas branch demonstrating integration of babylon.js & Fabric.js.
• Internationalization branch with all text extracted into JSON files ready to be translated. @ngx-translate was chosen over @angular/localize due to @angular/localize inability to change languages at runtime.
• Unity branch demonstrating how to compile a Unity WebGL web player as an Angular component.
  • The payload for the Unity app is currently weighing in at ~109MB uncompressed and ~12.8MB compressed with brotli.
  • Custom Nx scripts have been integrated to generate C# GraphQL types for communicating with the API server via GraphQL. This enables end-to-end typings.
  • The user management system has been unified across the entire monorepo and thus simplifies the creation of unique user experiences as a real-time web application. This starter kit now has the ability to render real-time scenes and load in models dynamically at runtime via Unity's Addressable system. It has never been easier to create exceptional enterprise grade metaverse experiences that are wired up to your own fleet of game servers delivering content on-demand.
  • A project management tool and game engine like Unity is necessary for complex projects that scales well as the number of team members grows. Unity is continuing to invest heavily into the web and has recently integrated experimental support for the new WebGPU standard that is nearing completion in being fully standardized. This enables utilizing Compute Shaders to tap into the massive parallelization power of the GPU.
  • The development experience is exquisite via the included recommended set of VSCode extensions and Unity as an Nx C# project. Making for a cross-platform development experience that is extraordinarily simple to set up and maintain.

---

🍡 Developer Operations

• Nx for project management to allow for the use of Nx Console extensions for VSCode. Nx Console is a GUI interface for monorepos that adds a lot of modern developer conveniences. It also helps to simplify the use of the various Angular & Nest code generation schematics available in the ecosystem.
• Angular Language Service for VSCode for modern IDE tooling.
• npm scripts for versioned releases of the Nest api server as a containerized Docker image. node:20-alpine is used as the Docker container base image and the appropriate tsconfig.app.json configurations are being applied for the Nest app.
• Example Kubernetes deployment scripts.
• Enforced code formatting via Prettier & import-sort, guaranteeing all contributions to the project are standardized with predictable structure and clear legibility.
• Commitizen for standardizing git commits.
• @nestjs-modules/mailer for automated emailing and pre-configured Handlebars e-mail templates for the various web portal's emailing needs. Handlebars has similar double bracket {{contextField}} template interpolation, akin to Angular templates. Custom HTML e-mail triggers within Nest are made very simple by simply passing a JSON context and the template's filename as parameters to the class injectable MailService.