Skip to main content

🧠 Configuration

Base options​

The eslint-config-sheriff package exports a sheriff function.
You can configure Sheriff as desired using a simple javascript object as the first input parameter of the sheriff function.
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. If you bootstrapped the config with create-sheriff-config some of these values will be inferred automatically from your project.

eslint.config.js
import sheriff from "eslint-config-sheriff";
import { defineFlatConfig } from "eslint-define-config";

// Sheriff configuration object
const sheriffOptions = {
  react: false,
  next: false,
  astro: false,
  lodash: false,
  playwright: false,
  jest: false,
  vitest: false,
};

export default defineFlatConfig([...sheriff(sheriffOptions)]);

Remodeling​

You can override any Sheriff rule as desired in the eslint.config.js file.

For example, let's say you want to disable a Sheriff rule, like import/first:

eslint.config.js
import sheriff from "eslint-config-sheriff";
import { defineFlatConfig } from "eslint-define-config";

const sheriffOptions = {
  react: false,
  next: false,
  astro: false,
  lodash: false,
  playwright: false,
  jest: false,
  vitest: false,
};

export default defineFlatConfig([
  ...sheriff(sheriffOptions),
  {
    rules: {
      "import/first": 0, // 'import/first' is now disabled everywhere.
    },
  },
]);

Likewise, let's say you want to enable a new rule:

eslint.config.js
import sheriff from "eslint-config-sheriff";
import { defineFlatConfig } from "eslint-define-config";

const sheriffOptions = {
  react: false,
  next: false,
  astro: false,
  lodash: false,
  playwright: false,
  jest: false,
  vitest: false,
};

export default defineFlatConfig([
  ...sheriff(sheriffOptions),
  {
    rules: {
      "import/first": 2, // 'import/first' is now enabled everywhere.
    },
  },
]);

This is just the standard behavior of the new configuration system of ESLint, which is being illustrated here for your convenience. Sheriff doesn't alter this in any way.

For more in-depth information, refer to the official docs.

Advanced configuration options​

The upcoming configuration options are kind of hidden options, tailored to serve only a niche group of users and designed to address specific use cases. Use these only if you end up needing them.

files​

Covered here: ♻ Migration guide

ignores​

By default, Sheriff will ignore certain filepaths, but you can choose to opt-out of this behavior.

API
ignores: {
  recommended: boolean;
  inheritedFromGitignore: boolean;
}

ignores.recommended​

A list of commonly ignored folders:

  • **/node_modules/**
  • **/dist/**
  • **/build/**
  • **/artifacts/**
  • **/coverage/**
  • eslint.config.{js,mjs,cjs,cts}

Example:

eslint.config.js
import sheriff from "eslint-config-sheriff";
import { defineFlatConfig } from "eslint-define-config";

const sheriffOptions = {
  react: false,
  next: false,
  astro: false,
  lodash: false,
  playwright: false,
  jest: false,
  vitest: false,
  ignores: {
    recommended: true, // true by default. False to disable.
  },
};

export default defineFlatConfig([...sheriff(sheriffOptions)]);

ignores.inheritedFromGitignore​

The same filepaths specified in your .gitignore file.

Example:

eslint.config.js
import sheriff from "eslint-config-sheriff";
import { defineFlatConfig } from "eslint-define-config";

const sheriffOptions = {
  react: false,
  next: false,
  astro: false,
  lodash: false,
  playwright: false,
  jest: false,
  vitest: false,
  ignores: {
    inheritedFromGitignore: true, // true by default. False to disable.
  },
};

export default defineFlatConfig([...sheriff(sheriffOptions)]);

pathsOverrides​

As outlined in the criteria page, Sheriff comes with sensible defaults. However, as your project grows, your team may come across the need to override some of these defaults. This option lets you do just that.

API
pathsOverrides: {
  tsconfigLocation: string | string[];
  tests: string[];
}

pathsOverrides.tsconfigLocation​

By default, Sheriff will use the project: true option to locate the tsconfig.json of your project.

But, if you have multiple tsconfig.json files in your project (like tsconfig.json, tsconfig.eslint.json, tsconfig.node.json, etc...), you can use this parameter to specify which config Sheriff will pickup.

You can pass it a path as a string (or a list of paths as a array of strings, see: one-tsconfigjson-per-package).

Example:

eslint.config.js
import sheriff from "eslint-config-sheriff";
import { defineFlatConfig } from "eslint-define-config";

const sheriffOptions = {
  react: false,
  next: false,
  astro: false,
  lodash: false,
  playwright: false,
  jest: false,
  vitest: false,
  pathsOverrides: {
    tsconfigLocation: "./tsconfig.eslint.json",
  },
};

export default defineFlatConfig([...sheriff(sheriffOptions)]);

pathsOverrides.tests​

By default, Sheriff will apply Jest or Vitest rules only on specific files.

API
[
  "**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts}",
  "**/tests/**/*.{js,mjs,cjs,ts,mts,cts}",
  "**/__tests__/**/*.{js,mjs,cjs,ts,mts,cts}"
]

This setting overrides this default.

It accepts an array of filepaths, dictaced by minimatch syntax.

Example:

eslint.config.js
import sheriff from "eslint-config-sheriff";
import { defineFlatConfig } from "eslint-define-config";

const sheriffOptions = {
  react: false,
  next: false,
  astro: false,
  lodash: false,
  playwright: false,
  jest: false,
  vitest: false,
  pathsOverrides: {
    tests: [
      "**/*.mySpecialName.{js,mjs,cjs,ts,mts,cts}",
      "**/mySpecialFolder/**/*.{js,mjs,cjs,ts,mts,cts}",
      "**/__mySpecialFolder__/**/*.{js,mjs,cjs,ts,mts,cts}",
    ],
  },
};

export default defineFlatConfig([...sheriff(sheriffOptions)]);

noRestrictedSyntaxOverride​

ESLint has a very useful rule called no-restricted-syntax. It accepts an array of objects. Each object represent a specific Javascript syntax feature that you may want to opt-out. Sheriff already come with a preconfigured no-restricted-syntax entry. However, if you need to customize it, you have a few options.

API
noRestrictedSyntaxOverride: {
  adjuncts: {
    selector: string;
    message: string;
  }[];
  allows: string[];
}

Override​

Override the rule in full. You provide your own no-restricted-syntax rule. You can do this you normally would, appending the rule to the FlatConfig array.

Extend​

Extend the Sheriff version of no-restricted-syntax. Use the key noRestrictedSyntaxOverride.adjuncts in the Sheriff configuration object.

Example:

eslint.config.js
import sheriff from "eslint-config-sheriff";
import { defineFlatConfig } from "eslint-define-config";

const sheriffOptions = {
  react: false,
  next: false,
  astro: false,
  lodash: false,
  playwright: false,
  jest: false,
  vitest: false,
  noRestrictedSyntaxOverride: {
    adjuncts: [
      {
        selector: "LabeledStatement",
        message:
          "Labels are a form of GOTO; using them makes code confusing and hard to maintain and understand.",
      },
      {
        selector: "ForInStatement",
        message:
          "for..in loops iterate over the entire prototype chain, which is virtually never what you want. Use Object.{keys,values,entries}, and iterate over the resulting array.",
      },
      {
        selector: "Identifier[name='Reflect']",
        message:
          "Avoid the Reflect API. It is a very low-level feature that has only rare and specific use-cases if building complex and hacky libraries. There is no need to use this feature for any kind of normal development.",
      },
    ],
  },
};

export default defineFlatConfig([...sheriff(sheriffOptions)]);

Shrink​

Shrink the Sheriff version of no-restricted-syntax. Use the key noRestrictedSyntaxOverride.allows in the Sheriff configuration object.

Example:

eslint.config.js
import sheriff from "eslint-config-sheriff";
import { defineFlatConfig } from "eslint-define-config";

const sheriffOptions = {
  react: false,
  next: false,
  astro: false,
  lodash: false,
  playwright: false,
  jest: false,
  vitest: false,
  noRestrictedSyntaxOverride: {
    allows: [
      "LabeledStatement",
      "ForInStatement",
      "Identifier[name='Reflect']",
    ],
  },
};

export default defineFlatConfig([...sheriff(sheriffOptions)]);