1 | # eslint plugin angular [![Npm version](https://img.shields.io/npm/v/eslint-plugin-angular.svg)](https://www.npmjs.com/package/eslint-plugin-angular) [![Npm downloads per month](https://img.shields.io/npm/dm/eslint-plugin-angular.svg)](https://www.npmjs.com/package/eslint-plugin-angular)
|
2 |
|
3 | > ESLint rules for your angular project with checks for best-practices, conventions or potential errors.
|
4 |
|
5 | [![Build Status](https://img.shields.io/travis/Gillespie59/eslint-plugin-angular/master.svg)](https://travis-ci.org/Gillespie59/eslint-plugin-angular)
|
6 | [![Npm dependencies](https://img.shields.io/david/Gillespie59/eslint-plugin-angular.svg)](https://david-dm.org/Gillespie59/eslint-plugin-angular)
|
7 | [![devDependency Status](https://img.shields.io/david/dev/Gillespie59/eslint-plugin-angular.svg)](https://david-dm.org/Gillespie59/eslint-plugin-angular#info=devDependencies)
|
8 | [![Join the chat at https://gitter.im/Gillespie59/eslint-plugin-angular](https://img.shields.io/gitter/room/nwjs/nw.js.svg)](https://gitter.im/Gillespie59/eslint-plugin-angular?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
9 | [![Coverage Status](https://img.shields.io/coveralls/Gillespie59/eslint-plugin-angular/master.svg)](https://coveralls.io/r/Gillespie59/eslint-plugin-angular?branch=master)
|
10 |
|
11 | ## Summary
|
12 |
|
13 | This repository will give access to new rules for the ESLint tool. You should use it only if you are developing an AngularJS application.
|
14 |
|
15 | Since the 0.0.4 release, some rules defined in [John Papa's Guideline](https://github.com/johnpapa/angular-styleguide/blob/master/a1) 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.
|
16 |
|
17 |
|
18 |
|
19 | ## Contents
|
20 |
|
21 | - [Usage with shareable config](#usage-with-shareable-config)
|
22 | - [Usage without shareable config](#usage-without-shareable-config)
|
23 | - [Rules](#rules)
|
24 | - [Need your help](#need-your-help)
|
25 | - [How to create a new rule](#how-to-create-a-new-rule)
|
26 | - [Default ESLint configuration file](#default-eslint-configuration-file)
|
27 | - [Who uses it?](#who-uses-it)
|
28 | - [Team](#team)
|
29 |
|
30 |
|
31 |
|
32 | ## Usage with [shareable](http://eslint.org/docs/developer-guide/shareable-configs.html) config
|
33 |
|
34 | Users may use the shareable [eslint-config-angular](https://github.com/dustinspecker/eslint-config-angular) to quickly setup eslint-plugin-angular. It also marks Angular as a global variable and defines required ESLint rules to use this plugin.
|
35 |
|
36 | 1. Install `eslint` as a dev-dependency:
|
37 |
|
38 | ```shell
|
39 | npm install --save-dev eslint
|
40 | ```
|
41 |
|
42 | 2. Install `eslint-plugin-angular` as a dev-dependency:
|
43 |
|
44 | ```shell
|
45 | npm install --save-dev eslint-plugin-angular
|
46 | ```
|
47 |
|
48 | 3. Install `eslint-config-angular` as a dev-dependency:
|
49 |
|
50 | ```shell
|
51 | npm install --save-dev eslint-config-angular
|
52 | ```
|
53 |
|
54 | 4. Use the shareable config by adding it to your `.eslintrc`:
|
55 |
|
56 | ```yaml
|
57 | extends: angular
|
58 | ```
|
59 |
|
60 |
|
61 |
|
62 | ## Usage without shareable config
|
63 |
|
64 | 1. Install `eslint` as a dev-dependency:
|
65 |
|
66 | ```shell
|
67 | npm install --save-dev eslint
|
68 | ```
|
69 |
|
70 | 2. Install `eslint-plugin-angular` as a dev-dependency:
|
71 |
|
72 | ```shell
|
73 | npm install --save-dev eslint-plugin-angular
|
74 | ```
|
75 |
|
76 | 3. Enable the plugin by adding it to your `.eslintrc`:
|
77 |
|
78 | ```yaml
|
79 | plugins:
|
80 | - angular
|
81 | ```
|
82 | 4. You can also configure these rules in your `.eslintrc`. All rules defined in this plugin have to be prefixed by 'angular/'
|
83 |
|
84 | ```yaml
|
85 | plugins:
|
86 | - angular
|
87 | rules:
|
88 | - angular/controller_name: 0
|
89 | ```
|
90 |
|
91 | ----
|
92 |
|
93 |
|
94 | ## Rules
|
95 |
|
96 | Rules in eslint-plugin-angular are divided into several categories to help you better understand their value.
|
97 |
|
98 |
|
99 | ### Possible Errors
|
100 |
|
101 | The following rules detect patterns that can lead to errors.
|
102 |
|
103 | * [module-getter](docs/module-getter.md) - disallow to reference modules with variables and require to use the getter syntax instead `angular.module('myModule')` ([y022](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y022))
|
104 | * [module-setter](docs/module-setter.md) - disallow to assign modules to variables (linked to [module-getter](docs/module-getter.md) ([y021](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y021))
|
105 | * [no-private-call](docs/no-private-call.md) - disallow use of internal angular properties prefixed with $$
|
106 |
|
107 | ### Best Practices
|
108 |
|
109 | These are rules designed to prevent you from making mistakes. They either prescribe a better way of doing something or help you avoid footguns..
|
110 |
|
111 | * [component-limit](docs/component-limit.md) - limit the number of angular components per file ([y001](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y001))
|
112 | * [controller-as-route](docs/controller-as-route.md) - require the use of controllerAs in routes or states ([y031](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y031))
|
113 | * [controller-as-vm](docs/controller-as-vm.md) - require and specify a capture variable for `this` in controllers ([y032](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y032))
|
114 | * [controller-as](docs/controller-as.md) - disallow assignments to `$scope` in controllers ([y031](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y031))
|
115 | * [deferred](docs/deferred.md) - use `$q(function(resolve, reject){})` instead of `$q.deferred`
|
116 | * [di-unused](docs/di-unused.md) - disallow unused DI parameters
|
117 | * [directive-restrict](docs/directive-restrict.md) - disallow any other directive restrict than 'A' or 'E' ([y074](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y074))
|
118 | * [empty-controller](docs/empty-controller.md) - disallow empty controllers
|
119 | * [no-controller](docs/no-controller.md) - disallow use of controllers (according to the component first pattern)
|
120 | * [no-inline-template](docs/no-inline-template.md) - disallow the use of inline templates
|
121 | * [no-run-logic](docs/no-run-logic.md) - keep run functions clean and simple ([y171](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y171))
|
122 | * [no-services](docs/no-services.md) - disallow DI of specified services for other angular components (`$http` for controllers, filters and directives)
|
123 | * [on-watch](docs/on-watch.md) - require `$on` and `$watch` deregistration callbacks to be saved in a variable
|
124 | * [prefer-component](docs/prefer-component.md) -
|
125 |
|
126 | ### Deprecated Angular Features
|
127 |
|
128 | These rules prevent you from using deprecated angular features.
|
129 |
|
130 | * [no-cookiestore](docs/no-cookiestore.md) - use `$cookies` instead of `$cookieStore`
|
131 | * [no-directive-replace](docs/no-directive-replace.md) - disallow the deprecated directive replace property
|
132 | * [no-http-callback](docs/no-http-callback.md) - disallow the `$http` methods `success()` and `error()`
|
133 |
|
134 | ### Naming
|
135 |
|
136 | These rules help you to specify several naming conventions.
|
137 |
|
138 | * [component-name](docs/component-name.md) - require and specify a prefix for all component names
|
139 | * [constant-name](docs/constant-name.md) - require and specify a prefix for all constant names ([y125](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y125))
|
140 | * [controller-name](docs/controller-name.md) - require and specify a prefix for all controller names ([y123](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y123), [y124](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y124))
|
141 | * [directive-name](docs/directive-name.md) - require and specify a prefix for all directive names ([y073](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y073), [y126](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y126))
|
142 | * [factory-name](docs/factory-name.md) - require and specify a prefix for all factory names ([y125](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y125))
|
143 | * [file-name](docs/file-name.md) - require and specify a consistent component name pattern ([y120](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y120), [y121](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y121))
|
144 | * [filter-name](docs/filter-name.md) - require and specify a prefix for all filter names
|
145 | * [module-name](docs/module-name.md) - require and specify a prefix for all module names ([y127](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y127))
|
146 | * [provider-name](docs/provider-name.md) - require and specify a prefix for all provider names ([y125](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y125))
|
147 | * [service-name](docs/service-name.md) - require and specify a prefix for all service names ([y125](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y125))
|
148 | * [value-name](docs/value-name.md) - require and specify a prefix for all value names ([y125](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y125))
|
149 |
|
150 | ### Conventions
|
151 |
|
152 | Angular often provide multi ways to to something. These rules help you to define convention for your project.
|
153 |
|
154 | * [di-order](docs/di-order.md) - require DI parameters to be sorted alphabetically
|
155 | * [di](docs/di.md) - require a consistent DI syntax
|
156 | * [dumb-inject](docs/dumb-inject.md) - unittest `inject` functions should only consist of assignments from injected values to describe block variables
|
157 | * [function-type](docs/function-type.md) - require and specify a consistent function style for components ('named' or 'anonymous') ([y024](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y024))
|
158 | * [module-dependency-order](docs/module-dependency-order.md) - require a consistent order of module dependencies
|
159 | * [no-service-method](docs/no-service-method.md) - use `factory()` instead of `service()` ([y040](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y040))
|
160 | * [one-dependency-per-line](docs/one-dependency-per-line.md) - require all DI parameters to be located in their own line
|
161 | * [rest-service](docs/rest-service.md) - disallow different rest service and specify one of '$http', '$resource', 'Restangular'
|
162 | * [watchers-execution](docs/watchers-execution.md) - require and specify consistent use `$scope.digest()` or `$scope.apply()`
|
163 |
|
164 | ### Angular Wrappers
|
165 |
|
166 | These rules help you to enforce the usage of angular wrappers.
|
167 |
|
168 | * [angularelement](docs/angularelement.md) - use `angular.element` instead of `$` or `jQuery`
|
169 | * [definedundefined](docs/definedundefined.md) - use `angular.isDefined` and `angular.isUndefined` instead of other undefined checks
|
170 | * [document-service](docs/document-service.md) - use `$document` instead of `document` ([y180](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y180))
|
171 | * [foreach](docs/foreach.md) - use `angular.forEach` instead of native `Array.prototype.forEach`
|
172 | * [interval-service](docs/interval-service.md) - use `$interval` instead of `setInterval` ([y181](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y181))
|
173 | * [json-functions](docs/json-functions.md) - use `angular.fromJson` and 'angular.toJson' instead of `JSON.parse` and `JSON.stringify`
|
174 | * [log](docs/log.md) - use the `$log` service instead of the `console` methods
|
175 | * [no-angular-mock](docs/no-angular-mock.md) - require to use `angular.mock` methods directly
|
176 | * [no-jquery-angularelement](docs/no-jquery-angularelement.md) - disallow to wrap `angular.element` objects with `jQuery` or `$`
|
177 | * [timeout-service](docs/timeout-service.md) - use `$timeout` instead of `setTimeout` ([y181](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y181))
|
178 | * [typecheck-array](docs/typecheck-array.md) - use `angular.isArray` instead of `typeof` comparisons
|
179 | * [typecheck-date](docs/typecheck-date.md) - use `angular.isDate` instead of `typeof` comparisons
|
180 | * [typecheck-function](docs/typecheck-function.md) - use `angular.isFunction` instead of `typeof` comparisons
|
181 | * [typecheck-number](docs/typecheck-number.md) - use `angular.isNumber` instead of `typeof` comparisons
|
182 | * [typecheck-object](docs/typecheck-object.md) - use `angular.isObject` instead of `typeof` comparisons
|
183 | * [typecheck-string](docs/typecheck-string.md) - use `angular.isString` instead of `typeof` comparisons
|
184 | * [window-service](docs/window-service.md) - use `$window` instead of `window` ([y180](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md#style-y180))
|
185 |
|
186 | ### Misspelling
|
187 |
|
188 | These rules help you avoiding misspellings.
|
189 |
|
190 | * [on-destroy](docs/on-destroy.md) - Check for common misspelling $on('destroy', ...).
|
191 |
|
192 |
|
193 | ----
|
194 |
|
195 |
|
196 | ## Need your help
|
197 |
|
198 | It is an opensource project. Any help will be very useful. You can :
|
199 | - Create issue
|
200 | - Send Pull Request
|
201 | - Write Documentation
|
202 | - Add new Features
|
203 | - Add new Rules
|
204 | - Improve the quality
|
205 | - Reply to issues
|
206 |
|
207 | All development happens on the `development` branch. This means all pull requests should be made to the `development` branch.
|
208 |
|
209 | 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.
|
210 |
|
211 |
|
212 |
|
213 | ## How to create a new rule
|
214 |
|
215 | We appreciate contributions and the following notes will help you before you open a Pull Request.
|
216 |
|
217 | ### Check the issues
|
218 |
|
219 | Have a look at the existing issues. There may exist similar issues with useful information.
|
220 |
|
221 | ### Read the documentation
|
222 |
|
223 | There are some useful references for creating new rules. Specificly useful are:
|
224 |
|
225 | * [The Context Object](http://eslint.org/docs/developer-guide/working-with-rules#the-context-object) - This is the most basic understanding needed for adding or modifying a rule.
|
226 | * [Options Schemas](http://eslint.org/docs/developer-guide/working-with-rules#options-schemas) - This is the preferred way for validating configuration options.
|
227 | * [Scope](http://estools.github.io/escope/Scope.html) - This is the scope object returned by `context.getScope()`.
|
228 |
|
229 | ### Files you have to create
|
230 |
|
231 | * `rules/<your-rule>.js`
|
232 | * JavaScript file with the new rule
|
233 | * The filename `<your-rule>` is exactly the usage name in eslint configs `angular/<your-rule>`
|
234 | * Have a look at the `angularRule` wrapper and the `utils` (both in `rules/utils/`) - they probably make things easier for you
|
235 | * Add a documentation comment to generate a markdown documentation with the `gulp docs` task
|
236 | * `test/<your-rule>.js`
|
237 | * Write some tests and execute them with `gulp test`
|
238 | * Have a look at the coverage reports `coverage/lcov-report/index.html`
|
239 | * `examples/<your-rule>.js`
|
240 | * Add some examples for the documentation
|
241 | * Run the `gulp docs` task to test the examples and update the markdown documentation
|
242 | * `docs/<your-rule>.md`
|
243 | * Generated by the `gulp docs` task
|
244 |
|
245 | ### Files you have to touch
|
246 |
|
247 | * `index.js`
|
248 | * Add your rule `rulesConfiguration.addRule('<your-rule>', [0, {someConfig: 'someValue'}])`
|
249 |
|
250 | ### Before you open your PR
|
251 |
|
252 | * Check that the `gulp` task is working
|
253 | * Commit generated changes in `README.md` and `docs/<your-rule>.md`
|
254 | * Open your PR to the `development` branch NOT `master`
|
255 |
|
256 | ### Rules specific for Angular 1 or 2
|
257 |
|
258 | 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.
|
259 |
|
260 | ```yaml
|
261 | plugins:
|
262 | - angular
|
263 |
|
264 | rules:
|
265 | angular/controller-name:
|
266 | - 2
|
267 | - '/[A-Z].*Controller$/'
|
268 |
|
269 | globals:
|
270 | angular: true
|
271 |
|
272 | settings:
|
273 | angular: 2
|
274 | ```
|
275 |
|
276 | And in your rule, you can access to this property thanks to the `context` object :
|
277 |
|
278 | ```javascript
|
279 | //If Angular 2 is used, we disabled the rule
|
280 | if(context.settings.angular === 2){
|
281 | return {};
|
282 | }
|
283 |
|
284 | return {
|
285 |
|
286 | 'CallExpression': function(node) {
|
287 | }
|
288 | };
|
289 | ```
|
290 |
|
291 |
|
292 |
|
293 | ## Default ESLint configuration file
|
294 |
|
295 | Here is the basic configuration for the rules defined in the ESLint plugin, in order to be compatible with the guideline provided by @johnpapa :
|
296 |
|
297 | ```yaml
|
298 | rules:
|
299 | no-use-before-define:
|
300 | - 0
|
301 | ```
|
302 |
|
303 |
|
304 |
|
305 | ## Who uses it?
|
306 |
|
307 | - [argo](https://github.com/albertosantini/argo)
|
308 | - [generator-gillespie59-angular](https://github.com/Gillespie59/generator-gillespie59-angular/)
|
309 | - [generator-ng-poly](https://github.com/dustinspecker/generator-ng-poly)
|
310 | - [JHipster](http://jhipster.github.io/)
|
311 | - [generator-gulp-angular](https://github.com/Swiip/generator-gulp-angular)
|
312 |
|
313 |
|
314 | ## Team
|
315 |
|
316 | [![Emmanuel Demey](https://avatars.githubusercontent.com/u/555768?s=117)](http://gillespie59.github.io/) | [![Tilman Potthof](https://avatars.githubusercontent.com/u/157532?s=117)](https://github.com/tilmanpotthof) | [![Remco Haszing](https://avatars.githubusercontent.com/u/779047?s=117)](https://github.com/remcohaszing) |
|
317 | :---:|:---:|:---:|
|
318 | [Emmanuel Demey](http://gillespie59.github.io/) | [Tilman Potthof](https://github.com/tilmanpotthof) | [Remco Haszing](https://github.com/remcohaszing) |
|