UNPKG

7.73 kBMarkdownView Raw
1# Neutrino ESLint Middleware
2
3`neutrino-middleware-eslint` is Neutrino middleware for linting source code using ESLint and eslint-loader.
4
5[![NPM version][npm-image]][npm-url]
6[![NPM downloads][npm-downloads]][npm-url]
7[![Join the Neutrino community on Spectrum][spectrum-image]][spectrum-url]
8
9## Requirements
10
11- Node.js v6.10+
12- Yarn or npm client
13- Neutrino v7
14
15## Installation
16
17`neutrino-middleware-eslint` can be installed via the Yarn or npm clients.
18
19#### Yarn
20
21```bash
22❯ yarn add neutrino-middleware-eslint
23```
24
25#### npm
26
27```bash
28❯ npm install --save neutrino-middleware-eslint
29```
30
31## Usage
32
33`neutrino-middleware-eslint` can be consumed from the Neutrino API, middleware, or presets. Require this package
34and plug it into Neutrino:
35
36```js
37// Using function middleware format
38const eslint = require('neutrino-middleware-eslint');
39
40// Usage shows default values
41neutrino.use(eslint, {
42 test: /\.(js|jsx)$/,
43 include: [], /* Should specify either include or exclude */
44 exclude: [], /* Should specify either include or exclude */
45 eslint: {
46 cwd: neutrino.options.root,
47 useEslintrc: false,
48 root: true,
49 extensions: ['js', 'jsx'],
50 plugins: ['babel'],
51 baseConfig: {},
52 envs: ['es6'],
53 parser: 'babel-eslint',
54 parserOptions: {
55 ecmaVersion: 2017,
56 sourceType: 'module',
57 ecmaFeatures: {
58 objectLiteralDuplicateProperties: false,
59 generators: true,
60 impliedStrict: true
61 }
62 },
63 settings: {},
64 globals: ['process'],
65 rules: {}
66 }
67});
68```
69
70- `test`: Test which files should be linted.
71- `include`: An array of paths to include in linting. Maps to Webpack's [`Rule.include`](https://webpack.js.org/configuration/module/#rule-include)
72- `exclude`: An array of paths to exclude from linting. Maps to Webpack's [`Rule.exclude`](https://webpack.js.org/configuration/module/#rule-exclude)
73- `eslint`: An ESLint CLIEngine configuration object for configuring ESLint. Use this to configure rules, plugins, and other [ESLint options](http://eslint.org/docs/user-guide/configuring).
74
75## Customization
76
77`neutrino-middleware-eslint` creates some conventions to make overriding the configuration easier once you are ready to
78make changes.
79
80### Rules
81
82The following is a list of rules and their identifiers which can be overridden:
83
84| Name | Description | Environments and Commands |
85| --- | --- | --- |
86| `lint` | By default, lints JS and JSX files from included directories using ESLint. Contains a single loader named `eslint`. | all |
87
88## Information
89
90By default this middleware will show errors and warnings in the console during development, and will cause a failure when
91creating a build bundle.
92
93---
94
95If you want your preset or middleware to also extend from another **ESLint configuration or preset** that you have made
96a dependency, you must use `baseConfig.extends` rather than just `extends`. This is a limitation of ESLint, not this
97middleware.
98
99---
100
101This middleware only configures a target environment for `es6`, leaving other build middleware free to add their own
102target environments. If your middleware puts restrictions on which environments it is capable of running, please
103document that clearly in your middleware.
104
105## eslint CLI
106
107_This is the recommended way to perform a one-off lint in a Neutrino project._
108
109You can also have Neutrino invoke ESLint for you if you wish to perform a one-time lint. This avoids needing to install
110ESLint manually, creating a `.eslintrc.js` file, or having to manage includes and ignores. As long as the ESLint
111middleware is loaded, you have access to a command to run ESLint from the command line.
112
113This middleware registers a command named `lint` which programmatically calls ESLint and prints the results to
114the console.
115
116```bash
117❯ neutrino lint
118```
119
120```bash
121❯ neutrino lint --fix
122```
123
124## eslintrc Config
125
126If you cannot or do not wish to use Neutrino to execute one-off linting, you can still use ESLint manually.
127
128`neutrino-middleware-eslint` also provides a method for getting the ESLint configuration suitable for use in an eslintrc
129file. Typically this is used for providing hints or fix solutions to the development environment, e.g. IDEs and text
130editors. Doing this requires [creating an instance of the Neutrino API](https://neutrino.js.org/api) and providing the
131middleware it uses. If you keep all this information in a `.neutrinorc.js`, this should be relatively straightforward. By
132providing all the middleware used to Neutrino, you can ensure all the linting options used across all middleware will be
133merged together for your development environment, without the need for copying, duplication, or loss of organization and
134separation.
135
136This middleware registers another command named `eslintrc` which returns an ESLint configuration object suitable for
137consumption by the ESLint CLI. Use the Neutrino API's `call` method to invoke this command:
138
139_Example: Create a .eslintrc.js file in the root of the project, using `.neutrinorc.js` middleware._
140
141```js
142// .eslintrc.js
143
144// If you do not specify any middleware to call(),
145// it will use the local .neutrinorc.js file
146
147const { Neutrino } = require('neutrino');
148const api = Neutrino();
149
150module.exports = api.call('eslintrc');
151```
152
153_Example: Create a .eslintrc.js file in the root of the project, using specified middleware._
154
155```js
156// .eslintrc.js
157const { Neutrino } = require('neutrino');
158const api = Neutrino();
159
160module.exports = api.call('eslintrc', [
161 ['neutrino-middleware-eslint', {
162 eslint: {
163 rules: { semi: 'off' }
164 }
165 }],
166 'neutrino-preset-react'
167]);
168```
169
170If you are able, only use a `.eslintrc.js` file for editor hints, and use the Neutrino `lint` command for one-off linting
171or fixes.
172
173Projects may face a problem when their editor or IDE lints all files and highlights errors that were normally excluded
174from source, i.e. Neutrino's `include` and `exclude` options. This is because the ESLint CLI does not have a way to
175specify included and excluded files from configuration. If you still wish to use ESLint's CLI for linting, consider
176setting [CLI flags](http://eslint.org/docs/user-guide/command-line-interface#options) or using an
177[eslintignore](http://eslint.org/docs/user-guide/configuring#ignoring-files-and-directories) to choose which files to
178include or exclude from linting.
179
180Unfortunately ESLint does not provide the possibility to configure ignored paths from Neutrino configuration and exclude them
181from linting. Projects authors should define this manually in their project root directory in a `.eslintignore` file. This
182is one of the main reasons to prefer using the `lint` CLI command with this middleware, as it avoids a lot of manual
183configuration and boilerplate.
184
185`.eslintignore` file:
186
187```
188/build
189/*.*
190```
191
192ESLint will exclude built files and any files in the root directory (e.g. custom Neutrino configuration) but `src` and
193`test` folders will be still checked. `node_modules` are ignored by default in ESLint. More information can be found
194in the [ESLint user guide](http://eslint.org/docs/user-guide/configuring#ignoring-files-and-directories).
195
196## Contributing
197
198This middleware is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
199containing all resources for developing Neutrino and its core presets and middleware. Follow the
200[contributing guide](https://neutrino.js.org/contributing) for details.
201
202[npm-image]: https://img.shields.io/npm/v/neutrino-middleware-eslint.svg
203[npm-downloads]: https://img.shields.io/npm/dt/neutrino-middleware-eslint.svg
204[npm-url]: https://npmjs.org/package/neutrino-middleware-eslint
205[spectrum-image]: https://withspectrum.github.io/badge/badge.svg
206[spectrum-url]: https://spectrum.chat/neutrino