microsoft
@rushstack/eslint-plugin
This plugin implements supplementary rules for use with the @rushstack/eslint-config package,
which provides a TypeScript ESLint ruleset tailored for large teams and projects.
Please see that project's documentation
for details. To learn about Rush Stack, please visit: https://rushstack.io/
@rushstack/hoist-jest-mock
Require Jest module mocking APIs to be called before any other statements in their code block.
Rule Details
Jest module mocking APIs such as "jest.mock()" must be called before the associated module is imported, otherwise
they will have no effect. Transpilers such as ts-jest and babel-jest automatically "hoist" these calls, however
this can produce counterintuitive behavior. Instead, the hoist-jest-mocks lint rule simply requires developers
to write the statements in the correct order.
The following APIs are affected: 'jest.mock()', 'jest.unmock()', 'jest.enableAutomock()', 'jest.disableAutomock()', 'jest.deepUnmock()'.
For technical background, please read the Jest documentation here: https://jestjs.io/docs/en/es6-class-mocks
Examples
The following patterns are considered problems when @rushstack/hoist-jest-mock is enabled:
import * as file from './file'; // import statement
jest.mock('./file'); // error
test("example", () => {
jest.mock('./file2'); // error
});require('./file'); // import statement
jest.mock('./file'); // errorThe following patterns are NOT considered problems:
jest.mock('./file'); // okay, because mock() precedes the import below
import * as file from './file'; // import statement// These statements are not real "imports" because they import compile-time types
// without any runtime effects
import type { X } from './file';
let y: typeof import('./file');
jest.mock('./file'); // okay@rushstack/import-requires-chunk-name
Require each dynamic import() used for code splitting to specify exactly one Webpack chunk name via a magic comment.
Rule Details
When using dynamic import() to create separately loaded chunks, Webpack (and compatible bundlers such as Rspack) can assign a deterministic name if a /* webpackChunkName: 'my-chunk' */ or // webpackChunkName: "my-chunk" magic comment is provided. Without an explicit name, the bundler falls back to autogenerated identifiers (often numeric or hashed), which:
- Are less stable across refactors, hurting long‑term caching
- Make bundle analysis and performance troubleshooting harder
- Can produce confusing diffs during code reviews
This rule enforces that:
- Every
import(<specifier>)expression used for code splitting includes a chunk name magic comment inside its parentheses. - Exactly one chunk name is declared. Multiple chunk name comments (or a single comment containing multiple comma‑separated
webpackChunkNameentries) are flagged.
The chunk name must appear in either a block or line comment inside the import() call. Accepted forms:
import(/* webpackChunkName: 'feature-settings' */ './feature/settings');
import(
/* webpackChunkName: "feature-settings" */
'./feature/settings'
);
import(
// webpackChunkName: "feature-settings"
'./feature/settings'
);No options are currently supported.
For background on magic comments, see: https://webpack.js.org/api/module-methods/#magic-comments
Examples
The following patterns are considered problems when @rushstack/import-requires-chunk-name is enabled:
// Missing chunk name
import('./feature/settings'); // error// Multiple chunk name comments
import(
/* webpackChunkName: 'feature-settings' */
/* webpackChunkName: 'feature-settings-alt' */
'./feature/settings'
); // error// Multiple chunk names in a single comment (comma separated)
import(
/* webpackChunkName: 'feature-settings', webpackChunkName: 'feature-settings-alt' */
'./feature/settings'
); // errorThe following patterns are NOT considered problems:
// Single block comment with one chunk name
import(/* webpackChunkName: 'feature-settings' */ './feature/settings');// Multiline formatting with a block comment
import(
/* webpackChunkName: 'feature-settings' */
'./feature/settings'
);// Line comment form
import(
// webpackChunkName: 'feature-settings'
'./feature/settings'
);Notes
- If your bundler does not understand Webpack magic comments (e.g. plain Node ESM loader), disable this rule for that project.
- Choose stable, descriptive chunk names—avoid including hashes, timestamps, or environment‑specific tokens.
- Chunk names share a global namespace in the final bundle; avoid collisions to keep analysis clear.
Rationale
Explicit chunk naming improves cache hit rates, observability, and maintainability. Enforcing the practice via an ESLint rule prevents missing or duplicate declarations that could lead to unpredictable bundle naming.
@rushstack/no-backslash-imports
Prevent import and export specifiers from using Windows-style backslashes in module paths.
Rule Details
JavaScript module specifiers always use POSIX forward slashes. Using backslashes (e.g. import './src\utils') can lead to inconsistent behavior across tools, and may break resolution in some environments. This rule flags any import or export whose source contains a \ character and provides an autofix that replaces backslashes with /.
Examples
The following patterns are considered problems when @rushstack/no-backslash-imports is enabled:
import helper from './lib\\helper'; // error (autofix -> './lib/helper')
export * from './data\\items'; // errorThe following patterns are NOT considered problems:
import helper from './lib/helper';
export * from '../data/items';Notes
- Works for
import, dynamicimport(), andexport ... fromforms. - Loader/query strings (e.g.
raw-loader!./file) are preserved during the fix; only path separators are changed.
Rationale
Forward slashes are portable and avoid subtle cross-platform inconsistencies. Autofixing reduces churn and enforces a predictable style.
@rushstack/no-external-local-imports
Prevent relative imports that reach outside the configured TypeScript rootDir (if specified) or outside the package boundary.
Rule Details
Local relative imports should refer only to files that are part of the compiling unit: either under the package directory or (when a rootDir is configured) under that root. Reaching outside can accidentally couple a package to sibling projects, untracked build inputs, or files excluded from type checking. This rule resolves each relative import/ export source and ensures the target is contained within the effective root. If not, it is flagged.
Examples
Assume rootDir is src and the package folder is /repo/packages/example:
// In /repo/packages/example/src/components/Button.ts
import '../utils/file'; // error if '../utils/file' is outside src
import '../../../other-package/src/index'; // error (outside package root)// In /repo/packages/example/src/index.ts
import './utils/file'; // passes (inside rootDir)Notes
- Only relative specifiers are checked. Package specifiers (
react,lodash) are ignored. - If no
rootDiris defined, the package directory acts as the boundary. - Useful for enforcing project isolation in monorepos.
Rationale
Prevents accidental dependencies on files that aren’t part of the compilation or publishing surface, improving encapsulation and build reproducibility.
@rushstack/no-new-null
Prevent usage of the JavaScript null value, while allowing code to access existing APIs that
may require null.
Rule Details
Most programming languages have a "null" or "nil" value that serves several purposes:
- the initial value for an uninitialized variable
- the value of
x.yorx["y"]whenxhas no such key, and - a special token that developers can assign to indicate an unknown or empty state.
In JavaScript, the undefined value fulfills all three roles. JavaScript's null value is a redundant secondary
token that only fulfills (3), even though its name confusingly implies otherwise. The null value was arguably
a mistake in the original JavaScript language design, but it cannot be banned entirely because it is returned
by some entrenched system APIs such as JSON.parse(), and also some popular NPM packages. Thus, this rule aims
to tolerate preexisting null values while preventing new ones from being introduced.
The @rushstack/no-new-null rule flags type definitions with null that can be exported or used by others.
The rule ignores declarations that are local variables, private members, or types that are not exported.
If you are designing a new JSON file format, it's a good idea to avoid null entirely. In most cases
there are better representations that convey more information about an item that is unknown, omitted,
or disabled. If you do need to declare types for JSON structures containing null, rather than
suppressing the lint rule, you can use a specialized
JsonNull
type as provided by @rushstack/node-core-library.
Examples
The following patterns are considered problems when @rushstack/no-new-null is enabled:
// interface declaration with null field
interface IHello { hello: null; } // error
// type declaration with null field
type Hello = { hello: null; } // error
// type function alias
type T = (args: string | null) => void; // error
// type alias
type N = null; // error
// type constructor
type C = {new (args: string | null)} // error
// function declaration with null args
function hello(world: string | null): void {}; // error
function legacy(callback: (err: Error| null) => void): void { }; // error
// function with null return type
function hello(): (err: Error | null) => void {}; // error
// const with null type
const nullType: 'hello' | null = 'hello'; // error
// classes with publicly visible properties and methods
class PublicNulls {
property: string | null; // error
propertyFunc: (val: string | null) => void; // error
legacyImplicitPublic(hello: string | null): void {} // error
public legacyExplicitPublic(hello: string | null): void {} // error
}The following patterns are NOT considered problems:
// wrapping an null-API
export function ok(hello: string): void {
const innerCallback: (err: Error | null) => void = (e) => {}; // passes
return innerCallback(null);
}
// classes where null APIs are used, but are private-only
class PrivateNulls {
private pField: string | null; // passes
private pFunc: (val: string | null) => void; // passes
private legacyPrivate(hello: string | null): void { // passes
this.pField = hello;
this.pFunc(this.pField)
this.pFunc('hello')
}
}@rushstack/no-null
(Deprecated) Prevent usage of JavaScript's null keyword.
Rule Details
This rule has been superseded by @rushstack/no-new-null, and is maintained to support code that has not
migrated to the new rule yet. The @rushstack/no-null rule prohibits null as a literal value, but allows
it in type annotations. Comparisons with null are also allowed.
Examples
The following patterns are considered problems when @rushstack/no-null is enabled:
let x = null; // error
f(null); // error
function g() {
return null; // error
}The following patterns are NOT considered problems:
let x: number | null = f(); // declaring types as possibly "null" is okay
if (x === null) { // comparisons are okay
x = 0;
}@rushstack/no-transitive-dependency-imports
Prevent importing modules from transitive dependencies that are not declared in the package’s direct dependency list.
Rule Details
Packages should only import modules from their own direct dependencies. Importing a transitive dependency (available only because another dependency pulled it in) creates hidden coupling and can break when versions change. This rule detects any import path containing multiple node_modules segments (for relative paths) or any direct reference to a nested node_modules folder for package specifiers, flagging such usages.
Allowed exception: a single relative traversal into node_modules (e.g. import '../node_modules/some-pkg/dist/index.js') is tolerated to support bypassing package exports fields intentionally. Additional traversals are disallowed.
Examples
The following patterns are considered problems when @rushstack/no-transitive-dependency-imports is enabled:
// Transitive dependency via deep relative path
import '../../node_modules/some-pkg/node_modules/other-pkg/lib/internal'; // error (multiple node_modules segments)
// Direct package import that resolves into nested node_modules (caught via parsing)
import 'other-pkg/node_modules/inner-pkg'; // errorThe following patterns are NOT considered problems:
// Direct dependency
import 'react';
// Single bypass to reach a file export
import '../node_modules/some-pkg/dist/index.js';Notes
- Encourages declaring needed dependencies explicitly in
package.json. - Reduces breakage due to indirect version changes.
Rationale
Explicit declarations keep dependency graphs understandable and maintainable; avoiding transitive imports prevents fragile build outcomes.
@rushstack/no-untyped-underscore (Opt-in)
Prevent TypeScript code from accessing legacy JavaScript members whose name has an underscore prefix.
Rule Details
JavaScript does not provide a straightforward way to restrict access to object members, so API names commonly
indicate a private member by using an underscore prefix (e.g. exampleObject._privateMember). For inexperienced
developers who may be unfamiliar with this convention, in TypeScript we can mark the APIs as private or omit them
from the typings. However, when migrating a large code base to TypeScript, it may be difficult to declare types
for every legacy API. In this situation, the @rushstack/no-untyped-underscore rule can help.
This rule detects expressions that access a member with an underscore prefix, EXCEPT in cases where:
- The object is typed: specifically,
exampleObjecthas a TypeScript type that declares_privateMember; OR - The object expression uses: the
thisorsuperkeywords; OR - The object expression is a variable named
that. (In older ES5 code,thatwas commonly used as an alias forthisin unbound contexts.)
Examples
The following patterns are considered problems when @rushstack/no-untyped-underscore is enabled:
let x: any;
x._privateMember = 123; // error, because x is untyped
let x: { [key: string]: number };
x._privateMember = 123; // error, because _privateMember is not a declared member of x's typeThe following patterns are NOT considered problems:
let x: { _privateMember: any };
x._privateMember = 123; // okay, because _privateMember is declared by x's type
let x = { _privateMember: 0 };
x._privateMember = 123; // okay, because _privateMember is part of the inferred type
enum E {
_PrivateMember
}
let e: E._PrivateMember = E._PrivateMember; // okay, because _PrivateMember is declared by E@rushstack/normalized-imports
Require relative import paths to be written in a normalized minimal form and autofix unnecessary directory traversals.
Rule Details
Developers sometimes write relative paths with redundant traversals (e.g. import '../module' when already in the parent, or import '././utils'). This rule computes the shortest relative path between the importing file and target, rewrites it using POSIX separators, and ensures a leading ./ is present when needed. Non-relative (package) imports are ignored.
If the provided path differs from the normalized form, the rule reports it and autofixes to the canonical specifier while preserving loader/query suffixes.
Examples
The following patterns are considered problems when @rushstack/normalized-imports is enabled:
// Redundant parent traversal
import '../currentDir/utils'; // error (autofix -> './utils')
// Repeated ./ segments
import '././components/Button'; // error (autofix -> './components/Button')The following patterns are NOT considered problems:
import './utils';
import '../shared/types';Notes
- Only relative paths (
./or../) are normalized. - Helps produce deterministic diff noise and cleaner refactors.
Rationale
Consistent relative paths improve readability and make large-scale moves/renames less error-prone.
@rushstack/pair-react-dom-render-unmount
Require ReactDOM (legacy) render trees created in a file to be explicitly unmounted in that same file to avoid memory leaks.
Rule Details
React 18 introduced ReactDOM.createRoot() and root.unmount(), but many codebases still use the legacy APIs:
ReactDOM.render(element, container)ReactDOM.unmountComponentAtNode(container)
If a component tree is rendered and the container node is later discarded without an explicit unmount, detached DOM nodes and event handlers may remain in memory. This rule enforces a simple pairing discipline: the total number of render calls in a file must match the total number of unmount calls. If they differ, every render and unmount in the file is flagged so the developer can reconcile them.
The rule detects both namespace invocations (e.g. ReactDOM.render(...)) and separately imported named functions (e.g. import { render, unmountComponentAtNode } from 'react-dom'). Default or namespace imports (e.g. import * as ReactDOM from 'react-dom' or import ReactDOM from 'react-dom') are supported.
No configuration options are currently supported.
Examples
The following patterns are considered problems when @rushstack/pair-react-dom-render-unmount is enabled:
import * as ReactDOM from 'react-dom';
ReactDOM.render(<App /> , document.getElementById('root'));
// Missing matching unmountimport { render } from 'react-dom';
render(<App /> , document.getElementById('root'));
// Missing matching unmountComponentAtNodeimport { unmountComponentAtNode } from 'react-dom';
// Unmount without a corresponding render in this file
unmountComponentAtNode(document.getElementById('root')!);import { render, unmountComponentAtNode } from 'react-dom';
render(<A /> , a);
render(<B /> , b);
// Only one unmount
unmountComponentAtNode(a);
// "b"'s render is not pairedThe following patterns are NOT considered problems:
import * as ReactDOM from 'react-dom';
const rootEl = document.getElementById('root');
ReactDOM.render(<App /> , rootEl);
ReactDOM.unmountComponentAtNode(rootEl!);import { render, unmountComponentAtNode } from 'react-dom';
render(<A /> , a);
render(<B /> , b);
unmountComponentAtNode(a);
unmountComponentAtNode(b);
// All renders paired// No legacy ReactDOM render/unmount usage in this file
// (e.g. uses React 18 createRoot API or just defines components) — rule passesNotes
- The rule does not attempt dataflow analysis to verify the same container node is passed; it only enforces count parity.
- Modern React apps using
createRoot()should migrate to pairingroot.unmount(). This legacy rule helps older code until migration is complete. - Multiple files can coordinate unmounting (e.g. via a shared cleanup utility); in that case this rule will flag the imbalance—consider colocating the unmount or disabling the rule for that file.
Rationale
Unpaired legacy renders are a common cause of memory leaks and test pollution. A lightweight count-based heuristic catches most oversights without requiring complex static analysis.
@rushstack/typedef-var
Require explicit type annotations for top-level variable declarations, while exempting local variables within function or method scopes.
Rule Details
This rule is implemented to supplement the deprecated @typescript-eslint/typedef rule. The @typescript-eslint/typedef rule was deprecated based on the judgment that "unnecessary type annotations, where type inference is sufficient, can be cumbersome to maintain and generally reduce code readability."
However, we prioritize code reading and maintenance over code authorship. That is, even when the compiler can infer a type, this rule enforces explicit type annotations to ensure that a code reviewer (e.g., when viewing a GitHub Diff) does not have to rely entirely on inference and can immediately ascertain a variable's type. This approach makes writing code harder but significantly improves the more crucial activity of reading and reviewing code.
Therefore, the @rushstack/typedef-var rule enforces type annotations for all variable declarations outside of local function or class method scopes. This includes the module's top-level scope and any block scopes that do not belong to a function or method.
To balance this strictness with code authoring convenience, the rule deliberately relaxes the type annotation requirement for the following local variable declarations:
- Variable declarations within a function body.
- Variable declarations within a class method.
- Variables declared via object or array destructuring assignments.
Examples
The following patterns are considered problems when @rushstack/typedef-var is enabled:
// Top-level declarations lack explicit type annotations
const x = 123; // error
let x = 123; // error
var x = 123; // error// Declaration within a non-function block scope
{
const x = 123; // error
}The following patterns are NOT considered problems:
// Local variables inside function expressions are exempt
function f() { const x = 123; } // passes
const f = () => { const x = 123; }; // passes
const f = function() { const x = 123; } // passes// Local variables inside class methods are exempt
class C {
public m(): void {
const x = 123; // passes
}
}
class C {
public m = (): void => {
const x = 123; // passes
}
}// Array and Object Destructuring assignments are exempt
let { a, b } = { // passes
a: 123,
b: 234
}Links
- CHANGELOG.md - Find out what's new in the latest version
@rushstack/eslint-plugin is part of the Rush Stack family of projects.