Custom Formatters

Custom formatters let you display linting results in a format that best fits your needs, whether that’s in a specific file format, a certain display style, or a format optimized for a particular tool.

ESLint also has built-in formatters that you can use.

You can include custom formatters in your project directly or create an npm package to distribute them separately.

Create a Custom Formatter

Each formatter is a function that receives a results object and a context as arguments and returns a string. For example, the following is how the built-in JSON formatter is implemented:

//my-awesome-formatter.js
module.exports = function (results, context) {
	return JSON.stringify(results, null, 2);
};
1
2
3
4

A formatter can also be an async function (from ESLint v8.4.0), the following shows a simple example:

//my-awesome-formatter.js
module.exports = async function (results) {
	const formatted = await asyncTask();
	return formatted;
};
1
2
3
4
5

To run ESLint with this formatter, you can use the -f (or --format) command line flag. You must begin the path to a locally defined custom formatter with a period (.), such as ./my-awesome-formatter.js or ../formatters/my-awesome-formatter.js.

eslint -f ./my-awesome-formatter.js src/
1

The remainder of this section contains reference information on how to work with custom formatter functions.

The results Argument

The results object passed into a formatter is an array of LintResult objects containing the linting results for individual files. Here’s an example output:

[
	{
		filePath: "/path/to/a/file.js",
		messages: [
			{
				ruleId: "curly",
				severity: 2,
				message: "Expected { after 'if' condition.",
				line: 2,
				column: 1,
			},
			{
				ruleId: "no-process-exit",
				severity: 2,
				message: "Don't use process.exit(); throw an error instead.",
				line: 3,
				column: 1,