Extreme Angular: A Stricter Starter Template

Extreme Angular adds strict development tooling to a standard Angular project. Use it as a starter template or as a reference for configuring these tools in an existing project.

The underlying Angular project was generated with:

ng new --strict --zoneless --style=scss --ssr=false

Everything else is an additive tooling layer on top of the Angular CLI defaults.

Why Use Extreme Angular

Starting a new Angular project with ng new gives you a working app, but not the tooling layer that teams typically add over time. Extreme Angular bridges that gap:

• ESLint with angular-eslint, typescript-eslint (strict + stylistic), accessibility rules, and JSON linting
• Prettier with plugins for import sorting, CSS property ordering, and shell script formatting
• Stylelint for CSS and SCSS
• CSpell for spell checking
• Husky + lint-staged for pre-commit linting and pre-push validation
• Commitlint for conventional commit messages
• GitHub Actions CI for pull request validation
• Stricter TypeScript via an extra compiler flag and fully type-checked linting

These tools are configured to work together without conflicts. Nothing here deviates from standard Angular — the official Angular documentation applies without modification.

Contributing

We welcome contributions! Please see our Contributing Guidelines for details on how to get started.

Found an issue? Check the existing issues first, then create a new one if needed.

Getting Started

Clone the repository and install dependencies (replace my-project with your project name):

git clone --depth=1 --origin=upstream https://github.com/joematthews/extreme-angular.git my-project
cd my-project
npm install

Using --origin=upstream names the remote upstream instead of origin, making it possible to pull in updates later.

Search and replace extreme-angular with your project name across the codebase, then start developing:

npm start

Dev Tools Implemented

How each tool is configured, and how to get the most out of it.

Use this script to run all checks against all project files:

npm run lint:all

TypeScript

TypeScript's strict mode and Angular's strictTemplates are both enabled by default, so this template relies on those defaults rather than setting them explicitly. On top of them, tsconfig.json adds one high-value compiler flag that ESLint cannot replicate: noUncheckedIndexedAccess, which adds undefined to array and object index access so the compiler forces explicit checks and prevents a common class of runtime errors.

Unused locals and parameters are intentionally left to ESLint's @typescript-eslint/no-unused-vars rule rather than the noUnusedLocals/noUnusedParameters compiler options, so an unused import while refactoring doesn't break ng build or ng serve.

Type checking commands:

npm run lint:tsc:app  # Check app files (*.ts)
npm run lint:tsc:spec # Check test files (*.spec.ts)
npm run lint:tsc:all  # Check all TypeScript files

Project structure:

The project uses TypeScript project references with separate configs for different contexts:

• tsconfig.app.json — Application code (src/**/*.ts)
• tsconfig.spec.json — Test files (src/**/*.spec.ts)
• tsconfig.node.json — Root config files (*.ts)

All extend tsconfig.json to share the same strict settings.

ESLint

ESLint is used for linting JavaScript, TypeScript, HTML, and JSON files in the project. The linting configuration is set in eslint.config.js, with specific overrides for the following file types: *.js, *.ts, *.spec.ts, *.html, and *.json.

To ensure effective linting for all project files, the following ESLint plugins are used:

• @angular-eslint
  • Uses recommended TypeScript and template rules unless explicitly disabled or modified.
  • @angular-eslint rules configuration matrix.
  • @angular-eslint/template rules configuration matrix.
• @typescript-eslint
  • Uses both strict-type-checked and stylistic-type-checked rule sets.
  • typescript-eslint rules configuration matrix.
• @vitest/eslint-plugin
  • Uses recommended rule set for Vitest test files.
  • @vitest/eslint-plugin rules.
• eslint-plugin-jsonc
  • Uses recommended rule set.
  • eslint-plugin-jsonc rules configuration matrix.
• eslint-config-prettier
  • Disables rules that may conflict with Prettier formatting.

To lint all relevant files in the project (not just those in src/):

npm run lint

ESLint output is formatted using eslint-formatter-mo. To use default formatting, remove -f mo from the lint script in package.json.

Accessibility (a11y)

This project enables all the accessibility rules provided by angular-eslint by default (denoted by :accessibility: in the @angular-eslint/template rules configuration matrix linked above).

Includes rules for image alt text, form labels, no autofocus, valid ARIA, and more.

These rules are easier to work with if enabled early in the development process and early adoption of these rules is also very helpful for avoiding common accessibility antipatterns.

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.

Stylelint

Stylelint is used to lint CSS and SCSS files in the project. It is configured with the stylelint-config-standard and stylelint-config-standard-scss configurations.

Rules for linting are applied separately to .css and .scss files, and they can be customized in .stylelintrc.json.

To lint all CSS and SCSS files:

npm run lint:style

Prettier

Prettier is used to enforce consistent code formatting, reducing diffs by minimizing formatting changes.

The base settings in .prettierrc (printWidth: 100, singleQuote: true, plus the *.html Angular-parser override) match what ng new generates. This template adds the following enhancements:

htmlWhitespaceSensitivity: "ignore" — Trims unnecessary whitespace around and inside HTML elements for cleaner templates. Use   (non-breaking space) when you need to explicitly maintain spacing between inline elements.

Plugins:

• prettier-plugin-sh: Formats shell scripts, such as Git hooks.
• prettier-plugin-css-order: Automatically organizes SCSS/CSS properties using concentric-css
• prettier-plugin-organize-imports: Automatically organizes, arranges, and removes unused imports.

To format files within the project:

npm run format

To check if all files are properly formatted:

npm run lint:format

CSpell

CSpell is used for spell checking for all project files.

To add project-specific words, update .cspell.json.

The Code Spell Checker Extension for VS Code allows you to quickly add misspelled words to the configuration by selecting "Add to config: .cspell.json" from the 'Quick Fix' menu.

The following dictionaries have been enabled: bash, companies, cpp, csharp, css, filetypes, fonts, go, html, latex, misc, node, npm, php, powershell, python, softwareTerms, and typescript.

To find misspelled words in all files within the project:

npm run lint:spelling

Testing

Vitest is the default unit test runner for Angular. Tests run in Node.js using jsdom to simulate the DOM, providing fast test execution without browser overhead.

To run tests in watch mode:

npm test

To run tests once (for CI):

npm run test:ci

VS Code

The following VS Code extensions will be recommended when opening the project (.vscode/extensions.json):

• Angular
• Editorconfig
• Prettier
• ESLint
• Stylelint
• Code Spell Checker

The following VS Code settings have been set in .vscode/settings.json:

• Set Prettier as default formatter.
• Turn on format on save
• Turn on auto-save and set delay for 3 seconds (does not format).
• Disable VS Code linter for CSS/SCSS.
• Enable Stylelint linter CSS & SCSS.
• Switch to workspace version of TypeScript for IntelliSense

Husky, Commitlint, and Lint-Staged (Git hooks)

Husky is used to manage the pre-commit, pre-push, and commit-msg git hooks.

Commitlint is used to enforce good commit messages according to the @commitlint/config-conventional configuration in the commit-msg git hook. Additional Commitlint configuration is kept in commitlint.config.js.

Lint-staged is used to run Prettier, ESLint, Stylelint, and CSpell in the pre-commit git hook against all staged files. Lint-staged configuration is kept in .lintstagedrc.json

The two hooks are tuned for different speeds and scopes:

• pre-commit runs lint-staged against only the staged files, giving fast feedback on every commit.
• pre-push runs the full npm run ci:all (type-checking, every linter, and the tests), so a complete validation happens before any code leaves your machine.

Running the entire suite on push is intentional. It mirrors the GitHub Actions checks locally, and it is the primary safety net for anyone pushing to a remote that has no CI of its own, such as a self-hosted or bare SSH repository. Because pushes happen far less often than commits, the extra time is rarely noticeable, and the Shove Progress escape hatch is there for the moments it is.

Shove Progress

You can bypass the git hooks using git commit --no-verify and git push --no-verify. Or, use the shove script in emergencies when progress needs to be backed up quickly:

npm run shove

The shove script will stage all files, commit with the commit message wip: shoved, and then push.

Continuous Integration (CI) Using GitHub Actions

The on-pull-request.yml workflow triggers validate-code.yml to check all files and run tests when a pull request is opened or updated.

The output of these workflows can be found in the 'Actions' tab on the GitHub repository. To block merges until they pass, add a branch protection rule (or ruleset) that requires the validate-code / called-workflow status check — new repositories start unprotected.

To execute these checks and tests locally:

npm run ci:all

Optional Configuration

Internationalization (i18n)

Angular has powerful Internationalization capabilities.

If you plan to implement internationalization in the future, adding i18n attributes early on can make the process easier to scale naturally.

To enable the i18n ESLint rule, add the following rule to the *.html section of eslint.config.js:

"@angular-eslint/template/i18n": "error",

End to End Testing (e2e)

Angular has schematics available for several end to end testing frameworks. The Angular End to End Testing guide will walk you through the steps to set one up.

The eslint-plugin-playwright package has rules for the popular Playwright framework. To incorporate these rules, import the plugin in the eslint.config.js file and then add a new config object that targets e2e/**/*.spec.ts files:

import { playwright } from 'eslint-plugin-playwright';

  {
    files: ['e2e/**/*.spec.ts'],
    extends: [...playwright.configs['flat/recommended'], prettierConfig],
    rules: { ...playwright.configs['flat/recommended'].rules },
  },

Tips & Tricks

These are tips and tricks that are too opinionated or situational to include in the repository configuration or are not related to Angular project configuration.

Custom Formatting

This project uses Angular's formatting defaults: 2 space indentation, 100 character line width, and single quotes. Here's how to customize if needed:

Indentation — set indent_size in .editorconfig:

[*]
indent_size = 4

Line width — set printWidth in .prettierrc:

{
  "printWidth": 80
}

Double quotes — set singleQuote in .prettierrc and update .editorconfig for IDE support:

{
  "singleQuote": false
}

[*.ts]
quote_type = double
ij_typescript_use_double_quotes = true

After making changes, run npm run format to re-format all files.

Here are some reasons for sticking with the defaults:

• Angular's documentation and libraries use 2 space indentation and single quotes.
• 4 space indentation can look cramped with a 100 character line width.
• 100 characters balances readability with side-by-side editor layouts on modern displays.

Git Config

To automatically set the remote branch name to match the local branch name on push:

git config push.autoSetupRemote true

You can use VS Code to edit commit messages when using commands like git commit, git rebase, and git commit --amend. This will only work if the code command in the PATH. Follow these instructions to set up the VS Code cli on macOS if it is not already set up. Run this command to set it up:

git config core.editor "code --wait"

If you use GitHub, and you'd prefer to not show your email in public commits, set your email to the one found on your GitHub account settings under the 'Email' tab. This is the same email used by GitHub Desktop, and when edits are made directly on the GitHub site.

git config user.email "14097616+joematthews@users.noreply.github.com"

Inlay Hints in VS Code

Consider enabling inlay hints for JavaScript and TypeScript in VS Code. They make it easier to rely on TypeScript's type inference without feeling the need to specify types 'for visibility'. The linked VS Code docs cover the available javascript.inlayHints.* and typescript.inlayHints.* settings.

Font Ligatures

VS Code supports 'font ligatures', which render multi-character operators like => and !== as single glyphs. Popular code fonts that include them are Fira Code and JetBrains Mono. To install a font and turn ligatures on, follow Fira Code's VS Code instructions (the same steps work for any ligature font).

Shell Configuration Frameworks

• Oh My Zsh: Popular on macOS, where zsh is now default.
• Oh My Bash: Popular on Linux, where bash is usually default.
• Oh My Posh: Cross-platform. Popular on Windows. Works with many shells.
• Starship: Cross-platform. Written in Rust.

These are great frameworks for managing shell configuration. They include helpful functions, plugins, helpers, and themes.

Shell configuration frameworks are a quick way to add git branch & status information to the shell prompt.

JetBrains IDEs

Webstorm, Rider & RustRover are now free to use for non-commercial use!

Here are some tips for configuring the dev tools for this project in JetBrains IDEs:

• ESLint, Stylelint, Prettier — follow JetBrains' guides for ESLint and Prettier; Stylelint is set up the same way.
  • Double check all three plugins are installed.
  • Set configuration to 'Automatic' for each and match the file extensions found in the scripts section of package.json.
  • (Optional) Set "Run on save" for each plugin if preferred.
• Install the "CSpell Check" plugin to reduce conflicts with JetBrains' built-in spell-checking.
• (Optional) Set keymap to 'VS Code' or 'VS Code (macOS)' for an easier transition
• (Optional) Search for 'ligatures' in the settings to enable font ligatures. JetBrainsMono is capable of displaying ligatures and is installed with the IDE

Updating

If you don't have an upstream remote (e.g., you used "Use this template"), add one:

git remote add upstream https://github.com/joematthews/extreme-angular.git

Create a branch and merge the latest changes:

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

Resolve any merge conflicts, then install dependencies and validate:

npm install
npm run ci:all