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.

lemon-mart's Issues

just downloaded beta version

Schema validation failed with the following errors:
Data path ".builders['app-shell']" should have required property 'class'.
Error: Schema validation failed with the following errors:
Data path ".builders['app-shell']" should have required property 'class'.

Experiment with AppShell

Add responsive design to stepper

Vertical mode when using on mobile

entity model

site map

the decode function in jwt-decode is not working

Good morning,

I have bought your book and I am setting up the lemmon-mart project using angular 10.
I am currently implementing and integrating the AuthService.

But when I run my project in the chrome browser, I get the following error:

TypeError: jwt_decode__WEBPACK_IMPORTED_MODULE_3__ is not a function.

when the function decode is called.

I noticed, that you have upgraded the repo to the usage of Angular 10 as well.

Did you encounter the same error?
if yes, how did you solve the issue?

Thanks in advance for your help,

Joost

Transition to eslint

• Replace tslint with eslint
• Replace import-sort with eslint-plugin-simple-import-sort
• Update .vscode extensions

Error in auth.firebase.service.ts when Circelci builds the project

`ERROR in src/app/auth/auth.firebase.service.ts:55:34 - error TS2345: Argument of type 'OperatorFunction<firebase.User, User>' is not assignable to parameter of type 'OperatorFunction<User | null, User>'.
Type 'User | null' is not assignable to type 'User'.
Type 'null' is not assignable to type 'User'.

55 return this.afAuth.user.pipe(map(this.transformFirebaseUser))
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~`

Add global spinner to UiService

AuthService Injection Error

I am following the book as we go but seem to have got that error and im failing to get the App to display the corrrect page that is login

main.ts:6 ERROR NullInjectorError: R3InjectorError(AppModule)[AuthService -> AuthService]:
NullInjectorError: No provider for AuthService!
at NullInjector.get (core.mjs:8890:27)
at R3Injector.get (core.mjs:9334:33)
at R3Injector.get (core.mjs:9334:33)
at ChainedInjector.get (core.mjs:14018:36)
at lookupTokenUsingModuleInjector (core.mjs:4608:39)
at getOrCreateInjectable (core.mjs:4656:12)
at Module.ɵɵdirectiveInject (core.mjs:11801:19)
at NodeInjectorFactory.LoginComponent_Factory [as factory] (login.component.ts:25:28)
at getNodeInjectable (core.mjs:4862:44)
at instantiateAllDirectives (core.mjs:12629:27)

login screen

Mock ups

Fix memory leak issues

Whenever .subscribe is implemented on an Observable/Subject, there should be a corresponding .unsubscribe implemented on ngOnDestroy hook.

Update Readme

License

Hi,
I have enjoyed reading the book and I would like to use some code of the book and in this repository for my own projects. I haven't found an official license. May I ask if you provide a license.
Thanks in advance.

Auth service login exception handling not working in login component

Hello,

Firstly, well done on a great book, I'm finding it incredibly useful!

I have noticed something not working as expected though. Working at stage 8 with the auth.in-memory.service and the login component. If I try logging in with a username that does not end with @test.com an error should be returned which should then be displayed between the password input and the Login button. I'm not seeing that error when I enter an invalid email address.

Am I missing something here or is there a real problem?

Thanks,

Dean

Question in auth-http-interceptor.ts redirect

Should

        if (err.status === 401) {
          this.router.navigate(['/user/login'], {
            queryParams: { redirectUrl: this.router.routerState.snapshot.url },
          })
        }

be

        if (err.status === 401) {
          this.router.navigate(['/login'], {
            queryParams: { redirectUrl: this.router.routerState.snapshot.url },
          })
        }

I don't think the login route is /user/login unless I'm missing/mis-understanding something.

Improve rxjs performance with shareReplay and distinctUntilChanged

Update auth provider observables to utilize shareReplay and distinctUntilChanged to avoid unnecessary change detection.

More info:
https://www.learnrxjs.io/learn-rxjs/operators/multicasting/sharereplay
https://rxjs-dev.firebaseapp.com/api/operators/distinctUntilChanged

https://cartant.medium.com/rxjs-whats-changed-with-sharereplay-65c098843e95