Awesome
eslint plugin angular
![Npm downloads per month](https://img.shields.io/npm/dm/eslint-plugin-angular.svg)
ESLint rules for your angular project with checks for best-practices, conventions or potential errors.
Summary
This repository will give access to new rules for the ESLint tool. You should use it only if you are developing an AngularJS application.
Since the 0.0.4 release, some rules defined in John Papa's Guideline have been implemented. In the description below, you will have a link to the corresponding part of the guideline, in order to have more information.
Contents
- Usage with shareable config
- Usage without shareable config
- Rules
- Need your help
- How to create a new rule
- Default ESLint configuration file
- Who uses it?
- Team
Usage with shareable config
-
Install
eslint
as a dev-dependency:npm install --save-dev eslint
-
Install
eslint-plugin-angular
as a dev-dependency:npm install --save-dev eslint-plugin-angular
-
Use the shareable config by adding it to your
.eslintrc
:extends: plugin:angular/johnpapa
Usage without shareable config
-
Install
eslint
as a dev-dependency:npm install --save-dev eslint
-
Install
eslint-plugin-angular
as a dev-dependency:npm install --save-dev eslint-plugin-angular
-
Enable the plugin by adding it to your
.eslintrc
:plugins: - angular
-
You can also configure these rules in your
.eslintrc
. All rules defined in this plugin have to be prefixed by 'angular/'plugins: - angular rules: - angular/controller_name: 0
Rules
Rules in eslint-plugin-angular are divided into several categories to help you better understand their value.
Possible Errors
The following rules detect patterns that can lead to errors.
- avoid-scope-typos - Avoid mistakes when naming methods defined on the scope object
- module-getter - disallow to reference modules with variables and require to use the getter syntax instead
angular.module('myModule')
(y022) - module-setter - disallow to assign modules to variables (linked to module-getter (y021)
- no-private-call - disallow use of internal angular properties prefixed with $$
Best Practices
These are rules designed to prevent you from making mistakes. They either prescribe a better way of doing something or help you avoid footguns..
- component-limit - limit the number of angular components per file (y001)
- controller-as-route - require the use of controllerAs in routes or states (y031)
- controller-as-vm - require and specify a capture variable for
this
in controllers (y032) - controller-as - disallow assignments to
$scope
in controllers (y031) - deferred - use
$q(function(resolve, reject){})
instead of$q.deferred
- di-unused - disallow unused DI parameters
- directive-restrict - disallow any other directive restrict than 'A' or 'E' (y074)
- empty-controller - disallow empty controllers
- no-controller - disallow use of controllers (according to the component first pattern)
- no-inline-template - disallow the use of inline templates
- no-run-logic - keep run functions clean and simple (y171)
- no-services - disallow DI of specified services for other angular components (
$http
for controllers, filters and directives) - on-watch - require
$on
and$watch
deregistration callbacks to be saved in a variable - prefer-component -
Deprecated Angular Features
These rules prevent you from using deprecated angular features.
- no-cookiestore - use
$cookies
instead of$cookieStore
- no-directive-replace - disallow the deprecated directive replace property
- no-http-callback - disallow the
$http
methodssuccess()
anderror()
Naming
These rules help you to specify several naming conventions.
- component-name - require and specify a prefix for all component names
- constant-name - require and specify a prefix for all constant names (y125)
- controller-name - require and specify a prefix for all controller names (y123, y124)
- directive-name - require and specify a prefix for all directive names (y073, y126)
- factory-name - require and specify a prefix for all factory names (y125)
- file-name - require and specify a consistent component name pattern (y120, y121)
- filter-name - require and specify a prefix for all filter names
- module-name - require and specify a prefix for all module names (y127)
- provider-name - require and specify a prefix for all provider names (y125)
- service-name - require and specify a prefix for all service names (y125)
- value-name - require and specify a prefix for all value names (y125)
Conventions
Angular often provide multi ways to to something. These rules help you to define convention for your project.
- di-order - require DI parameters to be sorted alphabetically
- di - require a consistent DI syntax
- dumb-inject - unittest
inject
functions should only consist of assignments from injected values to describe block variables - function-type - require and specify a consistent function style for components ('named' or 'anonymous') (y024)
- module-dependency-order - require a consistent order of module dependencies
- no-service-method - use
factory()
instead ofservice()
(y040) - one-dependency-per-line - require all DI parameters to be located in their own line
- rest-service - disallow different rest service and specify one of '$http', '$resource', 'Restangular'
- watchers-execution - require and specify consistent use
$scope.digest()
or$scope.apply()
Angular Wrappers
These rules help you to enforce the usage of angular wrappers.
- angularelement - use
angular.element
instead of$
orjQuery
- definedundefined - use
angular.isDefined
andangular.isUndefined
instead of other undefined checks - document-service - use
$document
instead ofdocument
(y180) - foreach - use
angular.forEach
instead of nativeArray.prototype.forEach
- interval-service - use
$interval
instead ofsetInterval
(y181) - json-functions - use
angular.fromJson
and 'angular.toJson' instead ofJSON.parse
andJSON.stringify
- log - use the
$log
service instead of theconsole
methods - no-angular-mock - require to use
angular.mock
methods directly - no-jquery-angularelement - disallow to wrap
angular.element
objects withjQuery
or$
- timeout-service - use
$timeout
instead ofsetTimeout
(y181) - typecheck-array - use
angular.isArray
instead oftypeof
comparisons - typecheck-date - use
angular.isDate
instead oftypeof
comparisons - typecheck-function - use
angular.isFunction
instead oftypeof
comparisons - typecheck-number - use
angular.isNumber
instead oftypeof
comparisons - typecheck-object - use
angular.isObject
instead oftypeof
comparisons - typecheck-string - use
angular.isString
instead oftypeof
comparisons - window-service - use
$window
instead ofwindow
(y180)
Misspelling
These rules help you avoiding misspellings.
- on-destroy - Check for common misspelling $on('destroy', ...).
Need your help
It is an opensource project. Any help will be very useful. You can :
- Create issue
- Send Pull Request
- Write Documentation
- Add new Features
- Add new Rules
- Improve the quality
- Reply to issues
All development happens on the development
branch. This means all pull requests should be made to the development
branch.
If it is time to release, @Gillespie59 will bump the version in package.json
, create a Git tag and merge the development
branch into master
. @Gillespie59 will then publish the new release to the npm registry.
How to create a new rule
We appreciate contributions and the following notes will help you before you open a Pull Request.
Check the issues
Have a look at the existing issues. There may exist similar issues with useful information.
Read the documentation
There are some useful references for creating new rules. Specificly useful are:
- The Context Object - This is the most basic understanding needed for adding or modifying a rule.
- Options Schemas - This is the preferred way for validating configuration options.
- Scope - This is the scope object returned by
context.getScope()
.
Files you have to create
rules/<your-rule>.js
- JavaScript file with the new rule
- The filename
<your-rule>
is exactly the usage name in eslint configsangular/<your-rule>
- Have a look at the
angularRule
wrapper and theutils
(both inrules/utils/
) - they probably make things easier for you - Add a documentation comment to generate a markdown documentation with the
gulp docs
task
test/<your-rule>.js
- Write some tests and execute them with
gulp test
- Have a look at the coverage reports
coverage/lcov-report/index.html
- Write some tests and execute them with
examples/<your-rule>.js
- Add some examples for the documentation
- Run the
gulp docs
task to test the examples and update the markdown documentation
docs/<your-rule>.md
- Generated by the
gulp docs
task
- Generated by the
Files you have to touch
index.js
- Add your rule
rulesConfiguration.addRule('<your-rule>', [0, {someConfig: 'someValue'}])
- Add your rule
Before you open your PR
- Check that the
gulp
task is working - Commit generated changes in
README.md
anddocs/<your-rule>.md
- Open your PR to the
development
branch NOTmaster
Rules specific for Angular 1 or 2
We can use a property, defined in the ESLint configuration file, in order to know which version is used : Angular 1 or Angular 2. based on this property, you can create rules for each version.
plugins:
- angular
rules:
angular/controller-name:
- 2
- '/[A-Z].*Controller$/'
globals:
angular: true
settings:
angular: 2
And in your rule, you can access to this property thanks to the context
object :
//If Angular 2 is used, we disabled the rule
if(context.settings.angular === 2){
return {};
}
return {
'CallExpression': function(node) {
}
};
Default ESLint configuration file
Here is the basic configuration for the rules defined in the ESLint plugin, in order to be compatible with the guideline provided by @johnpapa :
rules:
no-use-before-define:
- 0
Who uses it?
Team
Emmanuel Demey | Tilman Potthof | Remco Haszing |