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.
@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 7. 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");
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 and 7.
It also works with any editor extensions that load ESLint as a library.
For an even leaner setup, @your-company/eslint-config
can provide the patch as its own dependency. See
@rushstack/eslint-config for a real world example
and recommended approach.
Links
@rushstack/eslint-patch
is part of the Rush Stack family of projects.