@rushstack/eslint-patch

What is @rushstack/eslint-patch?

The @rushstack/eslint-patch package is designed to enhance the integration of ESLint with monorepo setups, particularly those managed by Rush. It patches ESLint to allow for more flexible configuration file resolution, which is useful when dealing with multiple packages in a monorepo. This package helps to ensure that ESLint can correctly find and use configurations and plugins from common/shared locations.

What are @rushstack/eslint-patch's main functionalities?

Patching ESLint to support monorepo configurations

This code snippet is used at the beginning of an ESLint configuration file to apply the patch. It enables ESLint to resolve plugins and configurations from a common root in a monorepo, rather than from each package's local node_modules.

require('@rushstack/eslint-patch/modern-module-resolution');

Other packages similar to @rushstack/eslint-patch

eslint-plugin-import

This package provides a set of rules that help validate proper imports. It is similar to @rushstack/eslint-patch in that it helps manage module resolution, but it focuses on linting import/export syntax rather than patching ESLint's resolution algorithm.

eslint-config-airbnb

While not a direct alternative, eslint-config-airbnb provides a comprehensive set of ESLint rules, including those for import/export syntax. It can be used in monorepos but does not offer the same patching capabilities for ESLint resolution as @rushstack/eslint-patch.

eslint-plugin-monorepo

This plugin enforces monorepo-specific linting rules. It is similar in its focus on monorepos but differs from @rushstack/eslint-patch as it does not patch ESLint's behavior but rather provides additional rules to ensure monorepo best practices.

README

@rushstack/eslint-patch

A patch that improves how ESLint loads plugins when working in a monorepo with a reusable toolchain

What it does

This patch is a workaround for a longstanding ESLint feature request that would allow a shared ESLint config to bring along its own plugins, rather than imposing peer dependencies on every consumer of the config. In a monorepo scenario, this enables your lint setup to be consolidated in a single NPM package. Doing so greatly reduces the copy+pasting and version management for all the other projects that use your standard lint rule set, but don't want to be bothered with the details.

ESLint provides partial solutions such as the --resolve-plugins-relative-to CLI option, however they are awkward to use. For example, the VS Code extension for ESLint must be manually configured with this CLI option. If some developers use other editors such as WebStorm, a different manual configuration is needed. Also, the --resolve-plugins-relative-to parameter does not support multiple paths, for example if a config package builds upon another package that also provides plugins. See this discussion for additional technical background.

Why it's a patch

ESLint's long awaited module resolver overhaul still has not materialized as of ESLint 8. As a stopgap, we created a small .eslintrc.js patch that solves the problem adequately for most real world scenarios. This patch was proposed as an ESLint feature with PR 12460, however the maintainers were not able to accept it unless it is reworked into a fully correct design. Such a requirement would impose the same hurdles as the original GitHub issue; thus, it seems best to stay with the patch approach.

Since the patch is now in wide use, we've converted it into a proper NPM package to simplify maintenance.

How to use it

Add a require() call to the to top of the .eslintrc.js file for each project that depends on your shared ESLint config, for example:

.eslintrc.js

require("@rushstack/eslint-patch/modern-module-resolution");

// Add your "extends" boilerplate here, for example:
module.exports = {
  extends: ['@your-company/eslint-config'],
  parserOptions: { tsconfigRootDir: __dirname }
};

With this change, the local project no longer needs any ESLint plugins in its package.json file. Instead, the hypothetical @your-company/eslint-config NPM package would declare the plugins as its own dependencies.

This patch works by modifying the ESLint engine so that its module resolver will load relative to the folder of the referencing config file, rather than the project folder. The patch is compatible with ESLint 6, 7, and 8. It also works with any editor extensions that load ESLint as a library.

There is a second patch in this package that removes the restriction on eslint configuration package names. Similarly to the first, this patch is applied by adding a require() call to the top of the .eslintrc.js, for example:

.eslintrc.js

require("@rushstack/eslint-patch/modern-module-resolution");
require("@rushstack/eslint-patch/custom-config-package-names"); // <-- Add this line

// Add your "extends" boilerplate here, for example:
module.exports = {
  extends: [
    '@your-company/build-rig/profile/default/includes/eslint/node' // Notice the package name does not start with "eslint-config-"
  ],
  parserOptions: { tsconfigRootDir: __dirname }
};

For an even leaner setup, @your-company/eslint-config can provide the patches as its own dependency. See @rushstack/eslint-config for a real world example and recommended approach.

Links

• CHANGELOG.md - Find out what's new in the latest version

@rushstack/eslint-patch is part of the Rush Stack family of projects.