Compassionate Linting (
A tool for customizing messages and adding context links in ESLint. Let your contributors know why a rule is turned on, and what they can do to fix their code.
Compassion is a more active form of empathy.
– April Wensel
ESLint is a fantastic tool that lets us write better, more maintainable code. Unfortunately, when contributors get feedback from a linter, it usually comes across about as friendly as
You did something wrong. Here's a token to Google around for.
That's frustrating! Especially when your contributor doesn't know exactly what the rule is trying to enforce or, more importantly, why the project has it enabled.
We can do better, by sharing insight into our project's values and providing additional context right at the moment linting errors appear. This fosters a more aligned, less contentious development environment.
eslint-formatter-compassion helps provide this alignment by letting you add contextual links to
your own style guide (or any of the guides provided by this package) and modify
existing lint error messages to fit your organization's needs. Leave linting code up to ESLint, but
when it comes time to communicate with human engineers, grab the reins and set some better context.
eslint-formatter-compassion provides several out-of-the-box ESLint formatters that use all the
general guide data available. Getting started is as easy as telling ESLint which formatter to use.
# Assuming you already have eslint running in your project.# If not, see# Add eslint-formatter-compassion as a dependency.# If you're using NPM: npm install eslint-formatter-compassion --save-devyarn add -D eslint-formatter-compassion# Lint using one of the pre-baked all-guides-enabled formatters# The -f (or --format) flag lets you select a different formatter.eslint ./ -f './node_modules/eslint-formatter-compassion/formatters/pre-baked-with-all-guides/stylish'
This package provides three major component types:
- Guides optionally provide better messages or contextual links for linting failures.
- You can make your own to add your own context.
- Process the output of ESLint into something human readable a guide, to help augment their output.
- Prebaked All-in-one ESLint formatters
- With all our supported guides. Just pick one of the pre-built, ESLint-compatible formatters
- With all our supported guides. Just pick one of the pre-built, ESLint-compatible formatters from
You can roll your own formatter using
eslint-formatter-compassion as a base, or use one of the
pre-built formatters of your choice.
Guides are the data source for augmenting eslint output. They can provide replacement messages as
well as multiple context links. A sample guide for modifying ESLint's built-in
semi rule would
look something like this:
moduleexports =name: 'myguide' // Each guide is named for debugabilityschema: 1 // Schema to automatically detect future breaking changesrules:// A rules objectsemi:// Keys by ruleId// Optional message to override the default one provided by `semi`message: 'Automatic semicolon insertion is hard to grok, so we use semicolons in JS.'// Optional array of links to external context. In this case, a blog post.context: '';
If you'd like to use your own guide content, please see the section below on rolling your own formatter.
Compassionate Formatters are very similar to ESLint's formatters, with the exception that they take in an array of Guides, and augment their output with those Guides' data. Because they take an additional agument, Compassionate Formatters not compatible with ESLint right out of the box. If you'd like an easy start, see the Quick-Start section, which uses the pre-built, ESLint-compatible versions of these formatters. If you'd like to make your own or use custom guide information, see the section below on making your own custom formatter.
There are several pre-built format styles (based off of popular eslint-provided formatters) which
can be found in
are immediately usable with ESLint.
Currently, we have:
codeframeProviding the maximum context for a linting error.
- Based on ESLint's codeframe formatter.
stylishProviding a more compact view.
- Based on ESLint's stylish formatter.
visualstudioFor use in IDE tooltips.
- Based on ESLint's visualstudio formatter.
Each pre-built solution includes every available guide.
## Pass the path to your pre-baked formatter of choice using the -f or --format flageslint ./ -f './node_modules/eslint-formatter-compassion/formatters/pre-baked-with-all-guides/stylish'
If you'd like to add your own context links or message customization, you can add compose an
eslint-compatible formatter using the libraries and data provided by
// Load up all the guides we want to useconst airbnb = ;const eslint = ;const importGuide = ;const jsxA11y = ;const react = ;// Import the formatter we want to use for outputconst formatter = ;// Here are the custom rules.// In this case we'll override eslint's `semi` rule to have a better error// message as well as providing a link for context when the error is hit.const myGuide =name: 'myguide'schema: 1rules:semi:message:'Automatic semicolon insertion is hard to grok, so we choose to use semicolons in JS.'context: '';// We now pick the guides we want to include.// Order is important. It's usually best to start with 'eslint' and build// up from there. The order of precedence is right to left.const guides = eslint importGuide jsxA11y react airbnb myGuide;// finally, we export a single function, taking in the results from ESLint,// and returning the output of calling our formatter with our results, and// our guides.module ;
With the above file saved as
./my-formatter.js in your project, you can run eslint with your
custom compassionate formatter like this:
eslint ./ -f './my-formatter.js'