duluca/lemon-mart

Angular Template App with a Router-first architecture

LemonMart

The enterprise-ready Angular template project with REST and GraphQL RBAC pre-configured.

LemonMart was implemented with a Route-first architecture to designing SPAs.

See Changes section for important or breaking changes made to the project.

^{As of August 2023}

Get the book & watch the talk

LemontMart has been developed to support my book Angular for Enterprise Applications. You can get the book at any major bookstore or find the links at AngularForEnterprise.com.

Watch the talk on Architecture for Scalable Angular Apps on Pluralsight.

Check out the slides for Architecture for Scalable Angular Apps free at Slides.com.

Check out LocalCast Weatherto learn Angular, Material, and RxJS fundamentals using OpenWeatherMap.org APIs at https://github.com/duluca/local-weather-app.

Build, debug, and publish Docker images with npm Scripts for Docker and achieve Blue-Green deployments on AWS Fargate with npm Scripts for AWS.

Router-first Architecture

A router-first architecture to SPA design will save development teams, large and small, significant waste in duplicative work and re-architecting of the code base to enable better collaboration or achieve sub-second first meaningful paints in your application.

In order to pull off a router-first implementation, you need to:

1. Define user roles and a site map early on,
2. Design with lazy loading in mind, leveraging router outlets, auxiliary paths, and smart link tracking,
3. Implement a walking-skeleton navigation experience and validate, allowing multiple teams to execute seamlessly,
4. Design around major data components, using stateless data-driven components using RxJS/BehaviorSubjects,
5. Be disciplined in sticking to a decoupled component architecture, allowing remixing the UX quickly to respond to changes in requirements without having to re-architect the codebase,
6. Differentiate between user controls and components to appropriately use binding, resolve, and auth guards,
7. With TypeScript classes, interfaces, enums, validators, and pipes to maximize code reuse

Design Artifacts

Head over to the Wiki for user roles, site maps, data entity diagrams, and user mock-ups: https://github.com/duluca/lemon-mart/wiki.

Building Lemon Mart

• npm run build:prod is used to build a production-optimized version of the app.
• npm run docker:debug to run tests and build a containerized version of the app.
• integration.Dockerfile is a multi-stage Dockerfile that can be used to consistently build and test the app in various CI environments. The optimized image generated in the last step can then be deployed to any Docker host, including AWS, Heroku, Vercel, and Azure.

Authentication

For demonstration purposes, the login screen shows the Authentication Mode of the app. There are three modes:

• InMemory: auth.in-memory.service.ts
• Custom: auth.custom.service.ts
• Custom GraphQL: auth.graphql.custom.service.ts
• Firebase: auth.firebase.service.ts

The current mode can be adjusted in environment.ts. You can see how each mode is implemented in the link source files above.

This is covered in more detail in Angular for Enterprise Applications, 3rd Edition.

Build Configurations

3 build configurations map to authentication modes:

1. Production:

Executing npm run build:prod or npx ng build --configuration production or npx ng build --configuration=production leverages InMemory authentication. Note that the fake credentials are documented on the Login screen.

2. Firebase:

Executing npx ng build --configuration=firebase leverages Firebase authentication. For this to work, you must set up your own Firebase back-end and create a user in the Firebase console.

3. Lemon-Mart-Server:

Executing npx ng build --configuration=lemon-mart-server leverages Custom authentication. This is implemented by the example project Lemon Mart Server, which is detailed below.

Lemon Mart Server

Lemon Mart Server is an easy-to-learn and use TypeScript Node.js server using Minimal MEAN for Lemon Mart.

To run Lemon Mart in a full-stack setup, visit https://github.com/duluca/lemon-mart-server.

Developers

This project is a sample implementation containing numerous recipes and design patterns useful for developing an Angular application.

If you'd like to use this project as a starter or a template project for your project, you can get many benefits from using a pre-configured project. Some of the benefits are:

• Optimized development experience for VS Code
• Lazy loading feature module configuration
• A responsive landing, login, and user profile experience
• Angular Material and Flex Layout configured for UI development
• npm scripts for style and lint checks, building docker containers, testing, or deploying your app
• CircleCI configuration for Continuous Integration
• Pre-wired extensible authentication and authorization module
• And many more.

Pre-requisites

• Do NOT install @angular/cli or typescript globally to avoid version mismatch issues across multiple projects.
  • Note: When creating new projects in the future, execute npx @angular/cli new app-name --routing to create a new Angular app with basic routing wired.
  • If you have trouble with this command, try npx -p @angular/cli new app-name --routing
• To run ng commands from within the project directory, preprend npx to commands, like npx ng build.
• To continue using ng without having to prepend npx, configure shell autofallback as described here: https://www.npmjs.com/package/npx#shell-auto-fallback.

Adapting the template

• Fork and clone this repo.
• Rename the repo on GitHub to match the name of your project.
• Search and replace references to lemon-mart with your project name and git repo.
• Remove manager, pos, and inventory folders and references to them from app-routing.module.ts.
• You may modify profile.component.ts and view-user.component.ts under the user folder to fit your needs.
• Edit lemonmart-theme.scss to match your desired color scheme.
• Now you may begin implementing your own feature modules.
  • Questions? Consider creating an issue on this repo and buying my book at AngularForEnterprise.com.

During Development

• Run npm start for a developmenet web server.
• Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files.
• Run npm test to execute the unit tests via Karma.
• Run npm run e2e to execute the end-to-end tests via Cypress.

Code scaffolding

• Run ng generate component component-name to generate a new component. You can also use ng generate directive|pipe|service|class|guard|interface|enum|module.

Further help with Angular CLI

To get more help on the Angular CLI use ng help or go check out the Angular CLI README.

Full-Stack Setup with Docker Compose and Deploying to AWS

See the example project here https://github.com/duluca/lemon-mart-server

Changes

Changes are inevitable to keep the project up-to-date with libraries, tools, patterns and practices. Below are some notable changes that differ from the 1st, 2nd, and 3rd edition of my book.

Angular 17

• Moved to control flow syntax
• Global spinner demonstrating SignalState

Angular 16

• Renamed projects from ch2 format to stage2, so they make sense in the 3rd edition.
• Dropped ch13 and ch14 as there are no meaningful changes between projects. Refer to the main application under src for reference.
• Replaced tslint with eslint
• Replaced protractor with cypress for e2e, added tests
• Removed SharedModule, and implemented shared components as Standalone components
• Moved to Standalone project configuration
• Added GraphQL auth provider
• Removed subsink in favor of takeUntilDestroyed

Angular 13-15

• Updated dev-norms.md
• Introduced ngx-mock to supplement angular-unit-test-helper for mocking components
• Replaced @angular/flex-layout with @ngbracket/ngx-layout
• Removed jsbeautify and import-sort in prep for migration to eslint
• Disabled code coverage in prep for migration to Jest
• Updated style and lint scripts
• Updated config.yml for CircleCI updates
• Refactored AuthGuard
• Replaced tslint with eslint
• Removed protractor and e2e scripts

Angular 12 configuration changes

• Enabled bundle budgets
• Introduction development configuration
• Made production configuration the default one
• Added npm run watch command
• Strict settings on by default
• When using mat-table the [dataSource] property should NOT be set using an async pipe. Correct use is [dataSource]="items$". See user-table.component.html.
• Use of FormGroupName in profile.component.html

Renamed master branch to main

If you already have a master branch locally, then execute the following commands:

git branch -m master main
git fetch origin
git branch -u origin/main main
git remote set-head origin -a

Augury

• Augury extension is deprecated. Get use Angular DevTools instead: https://angular.io/guide/devtools.