Angular ESLint
Monorepo for all the tooling which enables ESLint to lint Angular projects
This project is made possible thanks to the continued hard work going into https://github.com/typescript-eslint/typescript-eslint, and brilliant work on the original TSLint rule implementations in https://github.com/mgechev/codelyzer.
Feel free to begin playing with the tooling in your own projects and submit PRs with missing rules and bug fixes.
We would also be very grateful for documentation PRs!
Supported Angular CLI Versions
We support Angular CLI 10.1.0 and onwards, including Angular CLI 11.x. This range is also captured by our integration-tests package.
Please do not open issues related to unsupported versions of the Angular CLI.
Packages included in this project
Please follow the links below for the packages you care about.
-
@angular-eslint/builder- An Angular CLI Builder which is used to execute ESLint on your Angular projects using standard commands such asng lint -
@angular-eslint/eslint-plugin- An ESLint-specific plugin that contains rules which are specific to Angular projects. It can be combined with any other ESLint plugins in the normal way. -
@angular-eslint/template-parser- An ESLint-specific parser which leverages the@angular/compilerto allow for custom ESLint rules to be written which assert things about your Angular templates. -
@angular-eslint/eslint-plugin-template- An ESLint-specific plugin which, when used in conjunction with@angular-eslint/template-parser, allows for Angular template-specific linting rules to run. -
@angular-eslint/schematics- Schematics which are used to add and update configuration files which are relevant for running ESLint on an Angular workspace.
Migrating from Codelyzer and TSLint
We have some tooling to make this as automated as possible, but the reality is it will always be somewhat project-specific as to how much work will be involved in the migration.
Step 1 - Add relevant dependencies
The first step is to run the schematic to add @angular-eslint to your project:
ng add @angular-eslint/schematicsThis will handle installing the latest version of all the relevant packages for you and adding them to the devDependencies of your package.json.
Step 2 - Run the convert-tslint-to-eslint schematic on a project
The next thing to do is consider which "project" you want to migrate to use ESLint. If you have a single application in your workspace you will likely have just a single entry in the projects configuration object within your angular.json file. If you have a projects/ directory in your workspace, you will have multiple entries in your projects configuration and you will need to chose which one you want to migrate using the convert-tslint-to-eslint schematic.
You can run it like so:
ng g @angular-eslint/schematics:convert-tslint-to-eslint {{YOUR_PROJECT_NAME_GOES_HERE}}The schematic will do the following for you:
- Read your chosen project's
tslint.jsonand use it to CREATE a.eslintrc.jsonat the root of the specific project which extends from the root config (if you do not already have a root config, it will also add one automatically for you).- The contents of this
.eslintrc.jsonwill be the closest possible equivalent to yourtslint.jsonthat the tooling can figure out. - You will want to pay close attention to the terminal output of the schematic as it runs, because it will let you know if it couldn't find an appropriate converter for a TSLint rule, or if it has installed any additional ESLint plugins to help you match up your new setup with your old one.
- The contents of this
- UPDATE the project's
architectconfiguration in theangular.jsonto such that thelint"target" will invoke ESLint instead of TSLint. - UPDATE any instances of
tslint:disablecomments that are located within your TypeScript source files to their ESLint equivalent.
Now when you run:
npx ng lint {{YOUR_PROJECT_NAME_GOES_HERE}}...you are running ESLint on your project! 🎉
Step 3 - Remove root TSLint configuration and use only ESLint
Once you are happy with your ESLint setup, you simply need to remove the root-level tslint.json and potentially uninstall TSLint and any TSLint-related plugins/dependencies if your Angular CLI workspace is now no longer using TSLint at all.
Notes on ESLint Configuration
It's important to understand up front that using Angular with ESLint is actually an advanced/complex use-case because of the nature of the files involved:
- Angular projects use TypeScript files for source code
- Angular projects use a custom/extended form of HTML for templates (be they inline or external HTML files)
The thing is: ESLint understands neither of these things out of the box.
Fortunately, however, ESLint has clearly defined points of extensibility that we can leverage to make this all work.
For detailed information about ESLint plugins, parsers etc please review the official ESLint documentation: https://eslint.org
The key principal of our configuration required for Angular projects is that we need to run different blocks of configuration for different file types/extensions. In other words, we don't want the same rules to apply on TypeScript files that we do on HTML/inline-templates.
Therefore, the critical part of our configuration is the "overrides" array:
{
"overrides": [
/**
* -----------------------------------------------------
* TYPESCRIPT FILES (COMPONENTS, SERVICES ETC) (.ts)
* -----------------------------------------------------
*/
{
"files": ["*.ts"],
// ... applies a special processor to extract inline Component templates
// and treat them like HTML files
"extends": ["plugin:@angular-eslint/template/process-inline-templates"]
// ... other config specific to TypeScript files
},
/**
* -----------------------------------------------------
* COMPONENT TEMPLATES
* -----------------------------------------------------
*/
{
"files": ["*.html"],
// ... config specific to Angular Component templates
}
]
}
By setting up our config in this way, we have complete control over what rules etc apply to what file types and our separate concerns remain clearer and easier to maintain.
For a full reference configuration example check out the full manually configured Angular CLI integration test located within this monorepo. Check out the relevant configuration files:
- packages/integration-tests/fixtures/v1014-multi-project-manual-config/.eslintrc.json
- packages/integration-tests/fixtures/v1014-multi-project-manual-config/angular.json
If you are looking for general help in migrating specific rules from TSLint to ESLint, you can check out this incredible project that we depend on in our conversion schematic: https://github.com/typescript-eslint/tslint-to-eslint-config
Linting HTML files and inline-templates with the VSCode extension for ESLint
If you use vscode-eslint, and want to lint HTML files and inline-templates on your Angular Components, you will need to make sure you add the following to your VSCode settings.json:
// ... more config
"eslint.options": {
"extensions": [".ts", ".html"]
},
// ... more config
"eslint.validate": [
"javascript",
"javascriptreact",
"typescript",
"typescriptreact",
"html"
],
// ... more configPlease see the following issue for more information: microsoft/vscode-eslint#922
Usage without Angular CLI Builder
If you're using this without the Angular CLI Builder don't forget to include .html as one of the file extensions when running the eslint CLI, otherwise templates will not be linted, e.g.:
eslint --ext .ts,.html
Rules List
| ✅ = done |
| 🚧 = work in progress |