Sheriff
Note
For a better reading experience, explore the official docs.
π Table of Contents
- π Table of Contents
- π Description
- π οΈ Setup
- β¨ Features
- π₯οΈ Techs
- π Requirements
- 𧳠Eslint plugins
- π§Ά Rules
- π§ Configuration
- π
Prettier support
- π§ Prior art
- β» Migration guide
- 𧑠Contributing
- π€ Changelog
- π License
- π Roadmap
- π Faq
- π Acknowledgments
π Description
π₯³ Introduction
sheriff
is a comprehensive Eslint configuration. It supports various popular technologies.
β οΈ At the moment, sheriff
supports only Typescript codebases with modern Ecmascript standards. Support for vanilla Javascript will come at a later time. See: roadmap.
π Key points
- This library is pioneering in the adoption of the Eslint
FlatConfig
, introduced in Eslint v8.23.0.
sheriff
is very easy to get started with and use. It promotes a βzero overhead approachβ. See: philosophy.
- Itβs a "plug & play" solution but you can customize it as much as you want. See: features.
π€ Why / Motivations
Managing a complex Eslint configuration takes time and effort. sheriff
does it for you.
π Philosophy / Criteria
This library is very opinionated, but it's for the better. I took a lot of decisions so you don't have to 1.
You can now quickstart static analysis in all your Typescript projects with ease. It's just 1 create-sheriff-config
.
You can think of sheriff
like prettier
or create-react-app
. It's a tool that comes battery-packed with optimal defaults. It removes configuration decisions from the equation, so you or your team can focus on developing the actual product.
And if you don't like something, you can easily override it, and just as easily you can extend it. See: configuration.
π οΈ Setup
This config is highly opinionated, so make sure to meet the hard requirements in your project.
Then, let create-sheriff-config
handle the whole setup for you automatically, or do it yourself manually.
π€ Automatic setup (recommended)
Let the CLI take care of everything! Just run this command in your terminal:
β― npx create-sheriff-config
...and you are good to go! Happy hacking π
π« Manual setup
Follow these steps:
-
Install the package from npm.
β― npm install -D eslint-config-sheriff
β― yarn add -D eslint-config-sheriff
β― pnpm add -D eslint-config-sheriff
-
Create a eslint.config.js
2 file at the root of your project and copy/paste the contents of this snippet:
import sheriff from 'eslint-config-sheriff';
export default [
...sheriff,
{
files: ['**/*{js,ts,jsx,tsx}'],
},
];
or, if you already have a eslint.config.js
in your project, just append sheriff
to the configs array, like this:
import sheriff from 'eslint-config-sheriff';
export default [
...sheriff,
];
-
Configure sheriff (optional)
-
Setup prettier (optional)
β¨ Features
- β‘ Batteries included:
sheriff
is a all-in-one solution. You don't need to install or configure separately anything else. Everything is included here. - π No lock-in:
sheriff
is not a framework. You can extend the eslint.config.js
beyond sheriff
as much as you like, just like you normally would. Or you can disable any rule sheriff
comes with. sheriff
doesn't impose any limitation. See: configuration. - π Frictionless by design: to setup
sheriff
and take off, the only input required from the user is running the command npx create-sheriff-config
. The command will automatically infer the details of your project and figure out the optimal sheriff
configuration by itself. - β Interoperability: you can plop
sheriff
in your project at any moment. create-sheriff-config
will config automatically everything for you and will warn you if you need to take any special precautions. Bottom line: it's never too late to install sheriff
. - π Cutting-edge:
sheriff
is one of the first attempts in the wild to adhere to the new eslint configuration format, the FlatConfig
. You can use sheriff
to easily and safely migrate your project to the new config format without effort. See: migration guide. - π Sensible: Almost all of the rules I hand-picked in
sheriff
were chosen to counter some problematic real-world scenarios that have occurred in some projects. No bloat here. - ποΈ Configurable:
sheriff
is fully configurable with its own config file sheriffrc.json
. See: configuration. - π Modular:
sheriff
has opt-in support for a wide array of libraries. - β SemVer:
sheriff
releases follows Semantic Versioning with Conventional Commits standards.
π₯οΈ Techs
π Requirements
Hard requirements
Recommendations
𧳠Eslint plugins
π§Ά Rules
See Rules.
π§ Configuration
-
Configure sheriff
as desired in the sheriffrc.json
file 3.
Every config option can be set on/off (you just pass them a boolean value). As they are all opt-in, they are all disabled by default.
// sheriffrc.json (default)
{
react: false,
next: false,
lodash: false,
playwright: false,
}
-
Override any sheriff
rule as desired in the eslint.config.js
file.
For example:
import sheriff from 'eslint-config-sheriff';
export default [
...sheriff,
{
files: ['**/*{js,ts,jsx,tsx}'],
},
];
Let's say you want to disable a sheriff
rule, like import/first
:
import sheriff from 'eslint-config-sheriff';
export default [
...sheriff,
{
files: ['**/*{js,ts,jsx,tsx}'],
},
{
rules: {
'import/first': 0,
},
},
];
Likewise, let's say you want to enable a new rule:
import sheriff from 'eslint-config-sheriff';
export default [
...sheriff,
{
files: ['**/*{js,ts,jsx,tsx}'],
},
{
rules: {
'no-undef': 2,
},
},
];
This is just the standard behavior of the new configuration system of Eslint, which I'm illustrating here for your convenience. sheriff
doesn't alter this in any way.
For more in-depth information, refer to the official docs.
π
Prettier support
sheriff
tries to incorporate prettier out-of-the-box.
The create-sheriff-config
command will spin up for you a default .prettierrc.json
configuration. You can modify it if you need to, but it is discouraged. Act with caution.
If you don't use the create-sheriff-config
command, you will have to provide a prettier config yourself. Also don't forget the .prettierignore file.
If you already have a prettier config in your project, the create-sheriff-config
command won't create a new prettier config, nor will attempt to modify the existing one.
sheriff
comes with the rules of eslint-config-prettier out-of-the-box.
By design, sheriff
doesn't incorporate eslint-plugin-prettier. Its use is discouraged by the prettier team itself, as it just slows down your editor.
Instead, for your local editing experience, it's recommended to install a editor extension.
If you want to enforce Prettier at pre-commit stage, see the official docs.
To enforce Prettier in CI, see the CLI docs.
π§ Prior art
Related projects
Comparisons
The main difference between sheriff
and the other projects is that sheriff
is updated to the most recent version of Eslint and supports the new FlatConfig
instead of relying on weird hacks using the @rushstack/eslint-patch.
There are of course other differences as well, but you can get an idea for yourself by reading their READMEs.
β» Migration guide
- Start by running the
create-sheriff-config
command and follow the advices that it prints in the console. - If you are setting up
sheriff
in an already established codebase, make sure that the only eslint config file present in the whole project is the eslint.config.js
. - If you want to keep your existing custom rules on-top of
sheriff
, move them to the eslint.config.js
, after the sheriff
config array. Refer to the configuration instructions. - Make sure to uninstall all the packages that
sheriff
already incorporates out-of-the-box. Here is the list.
𧑠Contributing
TODO
π License
MIT License.
π€ Changelog
See Releases.
π Roadmap
π FAQ
- Why you didnβt include Eslint plugins/rules for "X" library?
- Cypress β Don't use Cypress. Use Playwright instead.
- Storybook β Storybook is still quite a niche library. Support for Storybook may come at a later time. Keep an eye on the roadmap.
π Acknowledgments
For some of this config i partially used eslint-config-red as a base.
Also took inspiration from eslint-config-airbnb for some of the rules in no-restricted-syntax
.
I don't take any attribution for the rules in the various eslint-plugins used here (except for the few that I personally created). Please consider starring the respective projects for the awesome work their authors made. sheriff
wouldn't be possible without their efforts.
The full list of the plugins used is here.