⛩ Zen ⛩

Nest + Prisma + Angular 🏮 Full Stack GraphQL Starter Kit

---

What is really nice about Nest and Angular is that their programming idioms carry over seamlessly between the two, allowing for frontend devs to contribute to the backend. Though, there are complexities in creating the GraphQL endpoint that exposes the various CRUD operations over the Prisma data model on the backend. A combination between Nest + Prisma + Angular has provided for new capabilities that the industry has not really seen before. This project code generates all the boilerplate required in bridging these 3 technologies together.

There is a tremendous amount of value to be gained by treating the schema.prisma file as the single source of truth and then code generating everything else from that. It guarantees consistency between the frontend and backend. It also centralizes the CRUD operations over all the Prisma models via a single import endpoint.

This project also provides solutions for the hardest parts of user authentication as well. I have strictly kept to the Angular and Nest best practices that are being utilized within the ecosystem. This project is an attempt to package the sum total of all the lessons I have learned and making it publicly available to the community. All the services being generated should be fairly self explanatory and lots of useful npm scripts have been provided for the various stages of development to deployment. Better documentation will come with time. 🍜

🎐 New contributors are welcome!

---

🍣 Project Setup Instructions - GitHub Repo

Requirements

• Node v18
• Docker or Rancher Desktop

# Project setup steps
git clone https://github.com/ZenSoftware/zen.git --depth=1
cd zen
cp .env.example .env

# Substitute npm for pnpm if you are using that
npm i
docker-compose up -d
npm run prisma:migrate

# Start the Nest API
npm run start:api

# Start the Angular site at localhost:4200
npm start

# Reload Apollo VSCode extension via command palette
>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 debounce 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 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 SCSS variables integrated for a large assortment of high quality color themes to choose from.

---

🎏 Optional Tech Integrations

• Electron branch with new npm script npm run start:electron to launch the app within Electron.
• Capacitor branch - planned
• 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.

---

🍡 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.
• Strict typings with Typescript for everything. Even the code generation tools are written in Typescript.
• 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:18-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.
• Compodoc to generate Nest & Angular documentation.