Choosing TypeScript ESLint rules is a trade-off between defect detection, developer feedback, and the cost of analyzing types. This reference explains which rules to enable first, when type-aware linting is worth the extra work, how to estimate its impact, and how to roll out a maintainable configuration with flat config.
Overview
TypeScript ESLint combines ESLint’s rule system with TypeScript-aware parsing and analysis. A useful setup does more than make formatting consistent: it catches unsafe assumptions, suspicious control flow, incorrect promise handling, and patterns that the TypeScript compiler alone may not flag.
The important distinction is whether a rule needs TypeScript’s type checker. Syntax-only rules can inspect the parsed code without loading a full project program. Type-aware rules can answer questions such as whether a value is actually a promise, whether a variable is nullable, or whether a type assertion is hiding an incompatible value. That additional context improves some checks, but it can increase lint time and configuration complexity.
Start with a small, high-value baseline rather than enabling every available rule. A practical baseline usually includes:
- The TypeScript ESLint recommended preset for common correctness issues.
- Rules that prevent unused variables, duplicate declarations, and accidental error suppression where those patterns matter to the project.
- Selected type-aware rules for promises, unsafe values, and unnecessary conditions.
- Separate stylistic decisions, such as naming conventions or semicolon preferences, so they do not obscure correctness failures.
Preset names and configuration APIs can change across major releases. Treat recommended, recommendedTypeChecked, and stricter presets as versioned building blocks: confirm the supported names in the version of typescript-eslint installed by your project before copying a configuration.
How to estimate
Estimate linting cost by comparing a baseline run with a candidate configuration. The goal is not to produce a universal benchmark; it is to measure the effect on your repository, CI environment, and developer workflow.
- Record a baseline. Run ESLint against the same file set used in CI and note elapsed time, memory symptoms, error count, warning count, and the number of files examined.
- Add rules in groups. Test syntax-only correctness rules first, then type-aware rules, then stylistic rules. Grouping makes it easier to identify which change affected performance or produced noisy findings.
- Separate cold and warm runs. A first run may include parser, project, or file-system work that is less visible on later runs. Measure both when local feedback speed is important.
- Calculate the practical impact. Use
lint overhead = candidate time - baseline time. Also track findings per changed file, because a rule that reports hundreds of legacy issues may be less useful initially than one that finds a few actionable defects. - Test changed-file linting. Full-repository checks belong in CI, but editors and pre-commit hooks should generally provide feedback on the files a developer is actively changing.
For a repeatable comparison, keep the Node.js version, dependency lockfile, ESLint command, file extensions, and ignore patterns constant. Do not compare a source-only run with a generated-code run or a local command with a CI command that includes different project packages.
A simple decision score can help teams prioritize rules:
rule value = defect impact + review value - false-positive cost - performance cost
This is not a scientific score. Use a small scale, such as low, medium, or high, and document the reasoning in the configuration. A rule may be worth enabling in a backend handling untrusted input but unnecessary in a small declaration-only package.
Inputs and assumptions
Rule categories
| Category | Typical value | False-positive risk | Performance | Good fit |
|---|---|---|---|---|
| Syntax and correctness | High | Low to medium | Low | Most TypeScript applications |
| Type-aware safety | High in boundary-heavy code | Medium | Medium to high | Services, libraries, and shared application code |
| Stylistic consistency | Project-dependent | Medium | Low | Teams with explicit review conventions |
| Strict or unsafe checks | High after cleanup | Medium to high | Medium to high | New codebases and controlled migrations |
These ratings are starting assumptions, not guarantees. Generated files, monorepos, project references, path aliases, and editor integrations can change the result. If your project has unresolved TypeScript configuration issues, fix those before judging type-aware linting. The guidance in TypeScript Strict Mode Rollout can help separate compiler migration work from lint migration work.
Rules worth evaluating first
@typescript-eslint/no-floating-promiseshelps identify promises that are started without being awaited, returned, handled, or intentionally ignored. It is especially useful in request handlers, jobs, and database code.@typescript-eslint/no-misused-promisesflags places where a promise is passed to an API that expects a synchronous callback or boolean-like result. Review each finding carefully because framework callback types can make legitimate patterns look suspicious.@typescript-eslint/no-unsafe-assignment,no-unsafe-call,no-unsafe-member-access, andno-unsafe-returnmake values originating fromanyvisible. They are powerful for API and untyped-library boundaries, but can create substantial migration work.@typescript-eslint/consistent-type-importscan make import intent clearer and reduce complications when code is transpiled or bundled with different module settings.@typescript-eslint/no-explicit-anyencourages safer alternatives, but use exceptions for genuine escape hatches and migration boundaries rather than forcing vague types.@typescript-eslint/no-unnecessary-conditioncan expose stale checks, but it depends on accurate compiler settings and type information. It is more useful once nullability is modeled consistently.
Use core ESLint rules where they understand JavaScript syntax adequately, and use the TypeScript-specific replacement when the rule must understand TypeScript syntax or types. Avoid enabling both versions of a rule when they overlap; disable the base rule when the TypeScript ESLint documentation recommends a replacement.
Worked examples
Flat-config starting point
A flat configuration commonly lives in eslint.config.mjs. The exact exported presets depend on the installed release, so treat this as a shape to verify rather than a promise that every version exposes identical names:
import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';
export default tseslint.config(
eslint.configs.recommended,
tseslint.configs.recommended,
{
files: ['**/*.ts', '**/*.tsx'],
rules: {
'@typescript-eslint/consistent-type-imports': 'warn',
'@typescript-eslint/no-explicit-any': 'warn'
}
}
);
When the baseline is clean, evaluate a type-checked preset or add targeted rules. Type-aware configurations normally require a parser project or project-service setting that lets the parser locate the relevant tsconfig. Keep the lint project aligned with the files being checked; an overly broad project can slow linting and an overly narrow one can produce parsing errors.
Turning findings into fixes
For a floating promise, do not silence the rule automatically. Decide whether the operation should be awaited, returned, caught, or explicitly marked as intentionally ignored. For an unsafe value from parsed JSON, add a runtime validation step at the boundary instead of merely asserting a type. This is where linting complements, rather than replaces, careful utility types for DTOs and API models.
For a project migrating from JavaScript, begin with warnings and restrict checks to changed files or selected directories. Then remove warnings by category: unsafe boundaries, promise handling, assertions, and finally stylistic exceptions. The file-by-file approach described in the JavaScript to TypeScript Migration Guide works well with this staged lint rollout.
When a rule is too expensive
If a type-aware rule makes editor feedback unacceptably slow, keep it in a CI configuration while using a lighter local configuration. Another option is to lint application source separately from generated files, tests, and build output. Do not hide performance problems with broad disables before checking project boundaries, ignore patterns, and duplicate parser work.
When to recalculate
Revisit your TypeScript ESLint rules whenever the inputs change. The most useful checkpoints are a major ESLint or TypeScript ESLint upgrade, a TypeScript compiler-configuration change, a move to or away from flat config, a monorepo restructure, or a noticeable change in CI and editor performance.
Recalculate after adding a large package, generated-code directory, project reference, or framework integration. React, Next.js, test runners, and build tools may each parse or transform files differently, so confirm that ESLint is checking the intended source and not reporting on artifacts. If aliases or module resolution change, review both parser project settings and editor behavior; the path-alias setup guide provides a broader checklist.
Use this maintenance checklist:
- Review the release notes and verify preset and parser option names.
- Run a baseline and candidate timing comparison on the same file set.
- Inspect newly enabled rules for duplicate coverage with the TypeScript compiler.
- Classify findings as bugs, design decisions, migration debt, or false positives.
- Convert stable warnings to errors in small groups, starting with rules that prevent real defects.
- Document justified exceptions close to the rule or in a project policy file.
- Keep CI authoritative while preserving fast changed-file feedback for developers.
A good configuration is not the one with the most rules. It is the one whose findings developers understand, whose performance fits the workflow, and whose exceptions are visible and deliberate. Repeating the measurement after dependency and project changes keeps TypeScript linting useful instead of allowing the configuration to become an inherited list of warnings.