This is an opinionated Angular starter project that enforces best practices and provides a robust foundation for building modern, accessible web applications using Angular and its ecosystem of tools and libraries. Please feel free to use this as-is, or as inspiration, for your next Angular project ❤️

You can run and explore extreme-angular on StackBlitz: https://stackblitz.com/github/joematthews/extreme-angular?preset=node

• Installation & Starting
• Key Features
  • Accessibility (a11y)
  • Internationalization (i18n)
  • Angular Material & Dark Theme
  • Server-side-rendering & Pre-rendering
  • Typescript
  • Prettier
  • Eslint
  • Stylelint
  • VSCode
  • Code Spell Checker
  • Commitizen & Commitlint
  • Husky & Lint-Staged
  • Notes directory
• Updating
• Tips & Tricks
  • NestJS
  • Inlay Hints
  • Font Ligatures
  • Catppuccin

These instructions assume you have installed git version control and the latest version of Node.js LTS.

To create a new project, I recommend cloning only the most recent commit and renaming the remote branch to 'upstream'. (Replace new_project_name with the name of your project):

git clone --depth=1 --origin=upstream [email protected]:joematthews/extreme-angular.git new_project_name

Change to the new project directory and install the dependencies:

cd new_project_name
npm install

Use the shortcut CTRL+SHIFT+H in VSCode to search and replace extreme-angular with your chosen project name.

To start the development server run npm start.

The goal of these changes is to enforce 'best practices' while still being 100% compatible with the latest Angular documentation.

extreme-angular enables all of the accessibility rules from angular-eslint by default including image alt text, form labels, no autofocus, valid ARIA, and more.

In my experience these rules are easy to work with if enabled early in the development process and early adoption of these rules is also very helpful for avoiding common accessibility anti-patterns.

If you run into a problem with any of these accessibility rules I encourage you to open up an issue so we can troubleshoot the the errors or concerns together.

For a full list of accessibility-centric rules, check out the angular-eslint template rules

The Accessibility in Angular guide is a great place to start learning about accessibility in Angular and it provides resources on the topic of accessibility.

Please let me know if more can be done to improve the accessibility of extreme-angular by creating an issue. Thank you.

Enables Internationalization and requires i18n attributes on all elements that include text.

Although you may not require internationalization capabilities right now, adding i18n attributes as-you-go may make it less painful to use internationalization in the future.

To disable i18n enforcement, set "@angular-eslint/template/i18n" to "off" within the *.html section of the .eslintrc.json file:

"rules": {
  "@angular-eslint/template/i18n": "off"
}

Enables Angular Material and uses a dark theme that automatically switches from dark to light based on the light/dark preference set in the OS. The default theme is dark.

Changes density to -2 to make the UI (including buttons) more compact and more inline with web expectations.

Downloads the Roboto font from the Google font api in the index.html file. The font is set in the styles.scss file.

Enables Animations for Angular Material and custom components.

Enables Server-side-rendering and pre-rendering to improve SEO and user experience. To start the SSR server run the following commands:

npm run build
npm run serve:ssr:new_project_name

Adds the following compiler options to the tsconfig.json file to help with writing cleaner code:

• exactOptionalPropertyTypes
• noUnusedLocals
• noUnusedParameters
• noUncheckedIndexedAccess

Uses Prettier to provide opinionated formatting so diffs contain less formatting changes and teams argue less about formatting in general.

In the .prettierrc.json file, htmlWhitespaceSensitivity is set to ignore to improve the formatting of templates. This will trim whitespace around and inside elements. Use   (non-breaking space) to explicitly enforce spacing between inline-elements.

The following prettier plugins are used:

• prettier-plugin-sh
  • Enables formatting of shell scripts; eg, git hooks.
• prettier-plugin-css-order
  • Automatically orders SCSS/CSS properties using concentric-css
• prettier-plugin-organize-imports
  • Automatically orders, arranges, and removes unused imports.

Use npm run format to format all relevant files within the project.

The .eslintrc.json file is set up to use overrides for each of the following file types: *.js, *.ts, *spec.ts, *.html, *.json, and *.md.

To help ensure all project files are linted, the following eslint plugins are used:

• @angular-eslint
  • Enables all rules for typescript and all rules for templates unless explicitly disabled or modified.
• @typescript-eslint
  • Uses both strict-type-checked and stylistic-type-checked rule sets.
• eslint-plugin-rxjs
  • Uses recommended rule set.
• eslint-plugin-jasmine
  • Uses recommended rule set.
• eslint-plugin-markdown
  • Uses recommended rule set.
• eslint-plugin-jsonc
  • Uses recommended rule set.
• eslint-config-prettier
  • Removes any rules that may conflict with prettier formatting.

Use npm run lint to lint all relevant files within the project.

Uses Stylelint to lint CSS and SCSS using the stylelint-config-standard and stylelint-config-standard-scss configurations.

Rules for stylelint are split between *.css & *.scss overrides and can be modified in the .stylelintrc.json file.

Use npm run lint:style to lint all styles within the project.

Recommends VSCode extensions for Angular, Editorconfig, Prettier, Eslint, Stylelint, Code Spell Checker, Intellicode, and Intellicode Completions automatically via a pop-up when the project is opened for the first time. These recommendations are set in the .vscode/extensions.json file.

Configures the following settings in the .vscode/settings.json file:

• Sets Prettier as default formatter
• Formats code, and fix linting errors (if possible), on save with CTRL+S or via the menu.
• Auto saves after 2 seconds (does not automatically format code or fix errors)

Enables spell checking for all project files.

Add project specific words to .cspell.json.

I highly recommend installing Code Spell Checker for VSCode. With this extension you can select "Add to config: .cspell.json" from the 'Quick Fix' menu of misspelled words.

Use npm run check-spelling to look for misspelled words in the project.

Uses Commitizen to suggest consistent formatting of commit messages.

On git commit, a interactive prompt will appear:

? Select the type of change that you're committing: (Use arrow keys)
❯ feat:     A new feature
  fix:      A bug fix
  docs:     Documentation only changes
  style:    Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  refactor: A code change that neither fixes a bug nor adds a feature
  perf:     A code change that improves performance
  test:     Adding missing tests or correcting existing tests

Uses Commitlint and @commitlint/config-conventional to enforce good commit messages. Commitlint can be configured in commitlint.config.js.

Uses Husky to manage the pre-commit, pre-push, prepare-commit-msg, and commit-msg git hooks.

Uses Lint-staged to run prettier, eslint, stylelint, cspell, and tsc-files against all staged files before committing to git.

Runs npm run test:ci before each push.

Runs commitizen wizard in the prepare-commit-msg hook and runs commitlint in the commit-msg hook.

Files in the ./notes directory are ignored by git but are searchable within VSCode.

This may be useful for keeping personal markdown files for notes or reference including:

• Notes about clients
• Todo lists
• Code snippets & notebooks (iTypescript, tslab, etc)

To pull in the latest changes, I recommend checking out a 'update' branch and merging the latest changes from upstream/main:

git checkout main && git pull
git checkout -b update
git merge upstream/main

You may have to resolve merge conflicts. After a successful merge, install dependencies and then format, lint, test, and fix any new errors for all files:

npm install
npm run format
npm run lint
npm run lint:style
npm run test

Merge the update branch back into the main branch:

git checkout main && git pull
git merge update

Finally, delete the update branch:

git branch -d update

These are tips and tricks I feel are too opinionated to include in the repository. If this section gets out of hand I will probably move it into a separate repository.

If you are looking for a full featured, robust, and enterprise-ready Typescript backend framework that pairs well Angular, then checkout the NestJS web framework project. NestJS has features similar to Spring Boot, .NET and other enterprise web frameworks.

I highly recommend enabling inlay hints in VSCode. They give me the confidence to use Typescript's type inference without feeling the need specify types 'for visibility'.

Add the following to your user settings to enable inlay hints for javascript & typescript:

{
  "editor.inlayHints.enabled": "onUnlessPressed",
  "javascript.inlayHints.enumMemberValues.enabled": true,
  "javascript.inlayHints.functionLikeReturnTypes.enabled": true,
  "javascript.inlayHints.parameterNames.enabled": "all",
  "javascript.inlayHints.parameterTypes.enabled": true,
  "javascript.inlayHints.propertyDeclarationTypes.enabled": true,
  "javascript.inlayHints.variableTypes.enabled": true,
  "typescript.inlayHints.enumMemberValues.enabled": true,
  "typescript.inlayHints.functionLikeReturnTypes.enabled": true,
  "typescript.inlayHints.parameterNames.enabled": "all",
  "typescript.inlayHints.parameterTypes.enabled": true,
  "typescript.inlayHints.propertyDeclarationTypes.enabled": true,
  "typescript.inlayHints.variableTypes.enabled": true
}

Use CTRL + ALT (or CTRL + OPTION on Mac) to temporarily disable hints -- Or, change editor.inlayHints.enabled to offUnlessPressed to reverse this behavior.

VSCode is capable of using 'font ligatures' -- not everyone likes font ligatures, but I really enjoy them.

The two most popular fonts that support font ligatures are Fira Code and Jet Brains Mono. I typically use the 'Regular' *.ttf variant of each font.

After you've downloaded and installed the font of your choice, you can set the font and enable font ligatures in your settings:

{
  "editor.fontFamily": "'Fira Code', Menlo, Monaco, 'Courier New', monospace",
  "editor.fontLigatures": true
}

These are excellent fonts for readability even if you choose to leave editor.fontLigatures disabled.

The fira code repository maintains a list of alternative fonts with ligatures.

Looking for a new theme to try? Catppuccin is great theme that I describe as 'modern Darcula'.

Catppuccin has 4 flavours: 🌻 Latte, 🪴 Frappé, 🌺 Macchiato, & 🌿 Mocha.

Catppuccin is everywhere. I also use it for my macOS terminal theme.

VSCode has two extensions: Catppuccin for VSCode and Catppuccin Icons for VSCode.

My favorite is 🪴 Frappé.