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
Note
If you run into any issues at all with installing, updating, or using extreme-angular, then please search through the issues. If you do not see a similar issue, then please create a new issue -- thank you! 🙏
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 git@github.com:joematthews/extreme-angular.git new_project_nameChange to the new project directory and install the dependencies:
cd new_project_name
npm installUse 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.
Note
If you're using VSCode and Chrome, then press F5 on the keyboard to start the app in debug mode.
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"
}
Note
Saving a document using VSCode will automatically add missing i18n attributes using eslint --fix.
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_nameNote
Replace new_project_name above with the name of your project.
Adds the following compiler options to the tsconfig.json file to help with writing cleaner code:
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+Sor 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)
Caution
Depending on the maturity of your project, it may be better to look at the release notes and commits and manually make changes instead of merging. If the Angular version has changed, then follow the instructions to update Angular first before attempting to merge or make changes.
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/mainYou 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 testMerge the update branch back into the main branch:
git checkout main && git pull
git merge updateFinally, delete the update branch:
git branch -d updateThese 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 gist.
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.
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é.