1 # Working with Custom Formatters
3 While ESLint has some built-in formatters available to format the linting results, it's also possible to create and distribute your own custom formatters. You can include custom formatters in your project directly or create an npm package to distribute them separately.
5 Each formatter is just a function that receives a `results` object and returns a string. For example, the following is how the `json` built-in formatter is implemented:
8 //my-awesome-formatter.js
9 module.exports = function(results) {
10 return JSON.stringify(results, null, 2);
14 To run ESLint with this formatter, you can use the `-f` (or `--format`) command line flag:
17 eslint -f ./my-awesome-formatter.js src/
20 In order to use a local file as a custom formatter, you must begin the filename with a dot (such as `./my-awesome-formatter.js` or `../formatters/my-awesome-formatter.js`).
22 ### The `data` Argument
24 The exported function receives an optional second argument named `data`. The `data` object provides extended information related to the analysis results. Currently, the `data` object consists of a single property named `rulesMeta`. This property is a dictionary of rule metadata, keyed with `ruleId`. The value for each entry is the `meta` property from the corresponding rule object. The dictionary contains an entry for each rule that was run during the analysis.
26 Here's what the `data` object would look like if one rule, `no-extra-semi`, had been run:
34 description: "disallow unnecessary semicolons",
35 category: "Possible Errors",
37 url: "https://eslint.org/docs/rules/no-extra-semi"
42 unexpected: "Unnecessary semicolon."
49 The [Using Rule metadata](#using-rule-metadata) example shows how to use the `data` object in a custom formatter. See the [Working with Rules](https://eslint.org/docs/developer-guide/working-with-rules) page for more information about rules.
51 ## Packaging the Custom Formatter
53 Custom formatters can also be distributed through npm packages. To do so, create an npm package with a name in the format of `eslint-formatter-*`, where `*` is the name of your formatter (such as `eslint-formatter-awesome`). Projects should then install the package and can use the custom formatter with the `-f` (or `--format`) flag like this:
56 eslint -f awesome src/
59 Because ESLint knows to look for packages beginning with `eslint-formatter-` when the specified formatter doesn't begin with a dot, there is no need to type `eslint-formatter-` when using a packaged custom formatter.
61 Tips for `package.json`:
63 * The `main` entry should be the JavaScript file implementing your custom formatter.
64 * Add these `keywords` to help users find your formatter:
66 * `"eslint-formatter"`
69 See all [formatters on npm](https://www.npmjs.com/search?q=eslint-formatter);
71 ## The `results` Object
73 The `results` object passed into a formatter is an array of objects containing the lint results for individual files. Here's some example output:
78 filePath: "path/to/file.js",
83 message: "Expected { after 'if' condition.",
86 nodeType: "IfStatement"
89 ruleId: "no-process-exit",
91 message: "Don't use process.exit(); throw an error instead.",
94 nodeType: "CallExpression"
100 fixableWarningCount: 0,
102 "var err = doStuff();\nif (err) console.log('failed tests: ' + err);\nprocess.exit(1);\n"
105 filePath: "Gruntfile.js",
109 fixableErrorCount: 0,
110 fixableWarningCount: 0
115 ### The `result` Object
117 <!-- This section is copied from the "Node.js API" page. Changes to this section should
118 also be manually applied to that page. -->
120 Each object in the `results` array is a `result` object. Each `result` object contains the path of the file that was linted and information about linting issues that were encountered. Here are the properties available on each `result` object:
122 * **filePath**: The absolute path to the file that was linted.
123 * **messages**: An array of `message` objects. See below for more info about messages.
124 * **errorCount**: The number of errors for the given file.
125 * **warningCount**: The number of warnings for the given file.
126 * **source**: The source code for the given file. This property is omitted if this file has no errors/warnings or if the `output` property is present.
127 * **output**: The source code for the given file with as many fixes applied as possible. This property is omitted if no fix is available.
129 ### The `message` Object
131 Each `message` object contains information about the ESLint rule that was triggered by some source code. The properties available on each `message` object are:
133 * **ruleId**: the ID of the rule that produced the error or warning.
134 * **severity**: the severity of the failure, `1` for warnings and `2` for errors.
135 * **message**: the human readable description of the error.
136 * **line**: the line where the issue is located.
137 * **column**: the column where the issue is located.
138 * **nodeType**: the type of the node in the [AST](https://github.com/estree/estree/blob/master/spec.md#node-objects)
142 ### Summary formatter
144 A formatter that only cares about the total count of errors and warnings will look like this:
147 module.exports = function(results) {
148 // accumulate the errors and warnings
149 var summary = results.reduce(
150 function(seq, current) {
151 seq.errors += current.errorCount;
152 seq.warnings += current.warningCount;
155 { errors: 0, warnings: 0 }
158 if (summary.errors > 0 || summary.warnings > 0) {
172 Running `eslint` with the previous custom formatter,
175 eslint -f ./my-awesome-formatter.js src/
178 Will produce the following output:
181 Errors: 2, Warnings: 4
184 ### Detailed formatter
186 A more complex report will look something like this:
189 module.exports = function(results, data) {
190 var results = results || [];
192 var summary = results.reduce(
193 function(seq, current) {
194 current.messages.forEach(function(msg) {
196 filePath: current.filePath,
198 ruleUrl: data.rulesMeta[msg.ruleId].docs.url,
199 message: msg.message,
204 if (msg.severity === 1) {
205 logMessage.type = "warning";
206 seq.warnings.push(logMessage);
208 if (msg.severity === 2) {
209 logMessage.type = "error";
210 seq.errors.push(logMessage);
221 if (summary.errors.length > 0 || summary.warnings.length > 0) {
222 var lines = summary.errors
223 .concat(summary.warnings)
229 msg.ruleId + (msg.ruleUrl ? " (" + msg.ruleUrl + ")" : "") +
245 So running `eslint` with this custom formatter:
248 eslint -f ./my-awesome-formatter.js src/
254 error space-infix-ops (https://eslint.org/docs/rules/space-infix-ops)
255 src/configs/bundler.js:6:8
256 error semi (https://eslint.org/docs/rules/semi)
257 src/configs/bundler.js:6:10
258 warning no-unused-vars (https://eslint.org/docs/rules/no-unused-vars)
259 src/configs/bundler.js:5:6
260 warning no-unused-vars (https://eslint.org/docs/rules/no-unused-vars)
261 src/configs/bundler.js:6:6
262 warning no-shadow (https://eslint.org/docs/rules/no-shadow)
263 src/configs/bundler.js:65:32
264 warning no-unused-vars (https://eslint.org/docs/rules/no-unused-vars)
265 src/configs/clean.js:3:6
268 ## Passing Arguments to Formatters
270 While custom formatter do not receive arguments in addition to the results object, it is possible to pass additional data into formatters.
272 ## Using Environment Variables
274 Custom formatters have access to environment variables and so can change their behavior based on environment variable data. Here's an example that uses a `AF_SKIP_WARNINGS` environment variable to determine whether or not to show warnings in the results:
277 module.exports = function(results) {
278 var skipWarnings = process.env.AF_SKIP_WARNINGS === "true"; //af stands for awesome-formatter
280 var results = results || [];
281 var summary = results.reduce(
282 function(seq, current) {
283 current.messages.forEach(function(msg) {
285 filePath: current.filePath,
287 message: msg.message,
292 if (msg.severity === 1) {
293 logMessage.type = "warning";
294 seq.warnings.push(logMessage);
296 if (msg.severity === 2) {
297 logMessage.type = "error";
298 seq.errors.push(logMessage);
309 if (summary.errors.length > 0 || summary.warnings.length > 0) {
310 var warnings = !skipWarnings ? summary.warnings : []; // skip the warnings in that case
312 var lines = summary.errors
335 You would run ESLint with this custom formatter and an environment variable set like this:
338 AF_SKIP_WARNINGS=true eslint -f ./my-awesome-formatter.js src/
344 error space-infix-ops
345 src/configs/bundler.js:6:8
348 src/configs/bundler.js:6:10
352 ### Complex Argument Passing
354 If you find the custom formatter pattern doesn't provide enough options for the way you'd like to format ESLint results, the best option is to use ESLint's built-in [JSON formatter](https://eslint.org/docs/user-guide/formatters/) and pipe the output to a second program. For example:
357 eslint -f json src/ | your-program-that-reads-JSON --option
360 In this example, the `your-program-that-reads-json` program can accept the raw JSON of ESLint results and process it before outputting its own format of the results. You can pass as many command line arguments to that program as are necessary to customize the output.
362 ## Note: Formatting for Terminals
364 Modern terminals like [iTerm2](https://www.iterm2.com/) or [Guake](http://guake-project.org/) expect a specific results format to automatically open filenames when they are clicked. Most terminals support this format for that purpose: