typebytes/angular-checklist

🔥 Curated list of common mistakes made when developing Angular applications

Angular Checklist

This repo contains the code for angular-checklist.dev.

---

🤔 What is it?

Angular Checklist is a curated list of items that we believe every application should follow. Over the past couple of years, we have been doing a lot of code reviews and have often seen the same mistakes being made again and again.

That's when we decided to create Angular Checklist.

It's a curated list of best practices to avoid some common pitfalls.

Therefore, we transformed a bunch of best practices and common mistakes into todo items.

The idea is that for all your projects, you can go over the checklist and see which items your projects already comply with and which you still have to put in some more effort!

To keep track of your progress, every group has a progress indicator which tells you how many items you have already checked. If the pie chart has been completely filled, congratulations 🎉 ... your project will definitely be on track to success 🏆!

👨‍💻 Who is behind this project?

This project is brought to you with ❤️ by Dominic Elm and Kwinten Pisman.

Core Maintainers

• Gerome Grignon

👷 Want to contribute?

If you want to add a checklist item, file a bug, contribute some code, or improve our documentation, read up on our contributing guidelines and code of conduct, and check out open issues as well as open pull requests to avoid potential conflicts.

📄 Licence

MIT License (MIT) © Dominic Elm and Kwinten Pisman

angular-checklist's Issues

Progressive Web App Functionality

It would be great to have this as an installable web app, I can implement this for you if you want.

• Create dev branch

• Create dev firebase project for a test hosting site "angular-checklist-dev"?

• ng add @angular/pwa

• add service worker to app.component.ts

• automatic update logic

• manual update logic

• manual update button

ng upgrade fails due to incompatible Deps

➜ ng update --all
Your global Angular CLI version (8.0.0) is greater than your local
version (7.3.8). The local Angular CLI version is used.

To disable this warning use "ng config -g cli.warnings.versionMismatch false".
                  Package "angular-checklist" has an incompatible peer dependency to "@angular/common" (requires "^4.0.0" (extended), would install "8.0.0").
                  Package "angular-checklist" has an incompatible peer dependency to "@angular/core" (requires "^4.0.0" (extended), would install "8.0.0").
                  Package "angular-checklist" has an incompatible peer dependency to "rxjs" (requires "^5.1.0", would install "6.5.2").
                  Package "angular-checklist" has an incompatible peer dependency to "zone.js" (requires "^0.8.4", would install "0.9.1").
Incompatible peer dependencies found. See above.

Add e2e tests

I think we should really have some e2e tests for this project to ensure that, when new features are added, we don't break existing functionality.

My preference would be to write mostly e2e tests for the checklist with Cypress. Cypress a fast and reliable testing framework and I have been using it for some of my projects. It really is reliable and writing tests is fun as well.

Here's a list of todo's that we could parallelize across multiple people.

1. Set up Cypress
2. project page
   • adding projects
   • editing
   • renaming
   • and deleting
3. checklist page
   • check / uncheck items
   • add / remove favorites
   • edit mode (check / uncheck categories, test if a popup is shown when the category has favorites, test if the content area is not actionable and no items can be toggled)
   • change project
   • search for items and categories
   • filter items
   • check / uncheck all
   • about dialog

If anyone wants to take some parts over, I am more than happy to provide assistance and help you out with getting Cypress up and running.

Add section about component styling

Hey guys,

It would be great to have a section about the best practices in component styling: Topics could be like:

• Using css / sass
• Using styleUrls
• Scoping (:host)
• How to use or import variables in css / sass

What do you think?

Translation Contribution

Motivation for behavior

Users want to be able to display in a suitable language by selecting their native language.

Tasks

• step 1. The ability to generate content.json in multiple languages
• step 2. transloco module setting
• step 3. Put transloco in html
• step 4. i18n build mechanism and firabase settings (maybe this step will be unnecessary with the transloco.)
• step 5. Translation of application json
• step 6. Translation of content markdown

To-Do

• Need to layout a language selection list that takes into account the responsive design
• Application part translation with angular i18n.
• Application part translation with transloco
• Checklist details (markdown) are managed by additional files like XXXX.ja-JP.md.
    - display English content if there is no corresponding file
    - need to add features to tools/build-checklist.ts
    - I think gitlocalize is a good tool.

Other

If continue to AoT build, url must be added one path. since I do not know firebase, I do not understand the influence. maybe this will be unnecessary with the transloco.

angular-checklist cli

Would be nice to have an angular-checklist cli, that would be able to run against an angular project and generate a report, same way as lighthouse does.

[Review][Architecture] put business logic into services

Description

Update the current snippets by using inject() for the dependency injection.

Don't completely agree with dont-use-property-bindings-to-pass-static-strings rule

Consider the following components structure:

@Component({
  selector: 'child',
  template: 'child'
})
export class Child {
  @Input() textProp: string;

  @Input() propForCheck: string;
}


@Component({
  selector: 'my-app',
  template: `
    <child textProp="someText" [propForCheck]="'checkMe'"></child>
  `
})
export class AppComponent {}

I distinguish two implementations for such cases:

ViewEngine (Angular 4-7...)

This renderer will generate ngfactory that will looks like:

function View_AppComponent_0(_l) {
        return jit_viewDef_1(0, [(_l()(),
        jit_elementDef_2(0, 0, null, null, 1, 'child', [['textProp', 'someText']], null, null, null, jit_View_Child_0_3, jit__object_Object__4)), jit_directiveDef_5(1, 49152, null, 0, jit_Child_6, [], {
            textProp: [0, 'textProp'],
            propForCheck: [1, 'propForCheck']
        }, null)], function(_ck, _v) {
            var currVal_0 = 'someText';
            var currVal_1 = 'checkMe';
            _ck(_v, 1, 0, currVal_0, currVal_1);
        }, null);
    }

where updateDirectives part is:

function(_ck, _v) {
   var currVal_0 = 'someText';
   var currVal_1 = 'checkMe';
   _ck(_v, 1, 0, currVal_0, currVal_1);
},

As we can see above Angular will still check our static text property regardless we didn't use property binding explicity.
So we can conclude that ViewEngine still treats "static attribute binding" as property binding that needs to be checked.

In addition, if we take a look at elements panel:

<child textprop="someText" ng-reflect-text-prop="someText"
               ng-reflect-prop-for-check="checkMe">child</child>

we can also notice textprop attribute.

In summary, I would say that using textProp="someText" instead of [textProp]="'someText" will not give us better performance since it's treated the same as property binding and also blows our html by adding attribute on element through.

Ivy(incoming new renderer)

In Ivy we will have ngDefinition with compiled template like:

var _c0 = ['textProp', 'someText', 1, 'propForCheck'];
...
template: function AppComponent_Template(rf, ctx) {
    if (rf & 1) { // insert mode
      jit_element_2(0, 'child', _c0);
    }
    if (rf & 2) { // update mode
      jit_elementProperty_3(0, 'propForCheck', jit_bind_4('checkMe'));
    }
},

Here we can apply that rule since our static property treats as attribute and won't be checked during CD cycle

Content: When and why to use a state management solution

What about some hints about the usage of state management in general? NGRX seems to be overused in the community. Mike Ryan's talk is a very good one on this topic: https://youtu.be/omnwu_etHTY

Can we provide some "real" examples of when state management is a good fit and when it might be enough the handle state with a behaviour subject?

TSError: ⨯ Unable to compile TypeScript:

tools/utils.ts(63,10): error TS2352: Conversion of type 'GrayMatterFile
the other. If this was intentional, convert the expression to 'unknown' fir
[1] Types of property 'data' are incompatible.
[1] Type '{ [key: string]: any; }' is not comparable to type 'Checklist
[1] Property 'title' is missing in type '{ [key: string]: any; }'.

put init logic in the ngOnInit lifecycle hook is incorrect

put init logic in the ngOnInit lifecycle hook is not the best practice.

Please have a look at this article on AngularInDepth

Content: Use modules to define features

A common mistake is to create an app with a long list of components instead of group these into feature modules.

What about add this item to architecture category?

[Typescript] Strict

Description

Add a Typescript checklist item about the strict configuration rule.
Even if introduced in Typescript and Angular a while ago, some projects do not include it and might not know the different strictness options.

[Performance] Lazy load animations

Description

add an item about using provideAnimationsAsyncin place of provideAnimations.
https://angular.dev/guide/animations#enabling-the-animations-module

NGRX actions update?

Hey, I was wondering if it makes sense to update this item on the checklist:
https://angular-checklist.io/default/checklist/ngrx/iglD3

It's about defining Actions as classes, like that:

  export enum AppActionTypes {
    APP_PAGE_LOAD_USERS = '[App Page] Load Users'
  }
  
  export class AppPageLoadUsers implements Action {
    readonly type = AppActionTypes.APP_PAGE_LOAD_USERS;
  }

However, based on the newest ngrx docs (https://ngrx.io/guide/store/actions), it maybe should look more like this:

  export const loadUsers = createAction('[App Page] Load Users');

What do you think about that?
I'm happy to update this content item, but I'm not sure if we want that, and if so, how many changes do we think it needs?
I'm not sure if "note + resources" makes much sense when using a new ngrx wrapper for actions.

Add missing items

There are a few things that we still need to add. In particular, it's the following items:

• use latest version of everything (General)
• category for Testing
• use cypress for integration and e2e tests (opinionated but we can mark it as optional in the UI, goes into Testing)
• only manipulate the DOM via the Renderer (Components)
• wrap globals in services
• use valueChanges over keyup event or a subject (Forms)
• use path mappings to simplify imports (Typescript)

Contributions are more than welcome 🤩If someone wishes to contribute with one of the items above, please create separate pull requests and follow our contributing guide.

I also want to point out again that this project is released with a Code of Conduct. By participating in this project you agree to abide by its terms.

Pre-rendering

As of right now, pre-rendering is no longer used. I am not sure if Universal makes much sense for the checklist, because the content currently lives on the client, meaning in the user's local storage. Prerending would improve the time to First Meaningful Paint but for this app it would also cause flickering when the client kicks in, because that's when data is pulled out of local storage and everything is replaced with the user's data. Since data lives in local storage we cannot transfer the state.

However, we could at least use Universal to pre-render an app-shell to show the above the fold content to the user for improved perceived startup performance. Angular Universal is already set up for static pre-rendering so we would need to also set up the app shell.

[Review][Components] don't use property bindings to pass static strings to native attributes

Description

Add an example with [attr.title] syntax when you need to pass an expression and can't just use title="some string value".

[General] NodeJS compatibility

Description

add an item in General to talk about the NodeJS compatibility, linking the official matrix: https://angular.dev/reference/versions#actively-supported-versions

[Review][Architecture] provide shared services only on root level

Description

The title is still valid as some people are creating multiple instances of a shared service by providing it at different levels of the injector tree.

However, the example should not be any longer about the SharedModuleas shown as a bad practice nowadays.

Tasks we need to do before going live

• Add licence
• Write proper README.md
• Create CONTRIBUTING.md with guidelines on how to contribute to this project
• Add Google Analytics

[Tooling] Add Eslint

add Eslint item

Validity of recommendations in checklist items

This is a question

Hi, are all articles listed on the site current and valid for the latest version of Angular?
I see that some recommendations are based on articles more than 2 years old (so more than 4 versions of Angular). Wouldn't it be possible to add to the recommendations to what version of Angular is this rule applicable? Like for example: Recommended for Angular versions 5 - latest. And consequently only specific versions of the Angular could be filtered out in the menu.

Add ngxs

Integrate FireStore to persists user projects

Currently, projects only live within local storage and the user's machine. They are not not persisted in a DB.

It would be cool if we integrated FireStore to synchronize the user's projects to a DB so that they are available on other machines as well.

This means we would also need Firebase authentication and whenever an action was dispatched that updated the one of the user's projects, we'd sync it with FireStore. For this we could use @ngrx/effects and encapsulate the side effects related to synchronization between the client and the DB.

Update to the latest version of Angular v13

@d3lm I'm working on updating to the latest version of angular. FYI

Angular Checklist down?

Hello,

I'm totally surprised that the website is down. Will the project continue?

Dead link on 'Components | put init logic in the ngOnInit lifecycle hook'

dead resource link:

• https://blog.angularindepth.com/the-essential-difference-between-constructor-and-ngoninit-in-angular-c9930c209a42

Good link:

• https://indepth.dev/the-essential-difference-between-constructor-and-ngoninit-in-angular/

[Components] replace @Inject decorator with inject function for proper typing or add to other inject list item

fix certificate error

Currently, https://www.angular-checklist.io/ shows insecure connection error.

We need to investigate what is causing this. Everything seems to work just fine when omitting www, e: https://angular-checklist.io/.

[Review][Components] minimize logic in templates

Description

Update the example with Signals, both as a way to modernize the practice and avoid calling a function in the template.

Migrate from Tslint to Eslint

Angular now stop giving support for tslint in angular v13. So we need to migrate from tslint to eslint for linting to work

Content(forms): Use ControlValueAccessor to create sub-forms

What about add this item? May sound irrelevant for small forms, but in my opinion important for huge forms

[Performance] remove trackby once new control flow is stable

As the new control flow syntax requires trackfor @for, it won't be required as part of the checklist once the new control flow is stable.

Website is down

It looks like the site might be down, are you aware of this? Do you know when it might be back?