• It banned usage of the unsafe "empty object" {} type
• It banned uses of dangerous or misleading built-in types: Function, Number, and so on
• It also allowed users to provide additional types to ban

Those are all great areas for linting! However, @typescript-eslint/ban-types suffered from several key design issues:

• By targeting all three areas of banning, it was hard to configure to only what a project needs
• It was overly strict on banning {}, to the point of confusing and inconveniencing users
• It was limited in what auto-fixes and edge cases it could handle for its default banned types

This post will explain how @typescript-eslint/ban-types came to be, its benefits and drawbacks, and the new rules that better handle its targeted functionality.

A Brief History of ban-types​

The first version of a "ban types" lint rule came from TSLint, a now-deprecated TypeScript-only linter predating typescript-eslint. TSLint's ban-type rule didn't ban any types by default. It would only ban types explicitly declared in a project's linting config.

When the rule was ported to @typescript-eslint/ban-types, it was changed to additionally lint against known dangerous built-in types by default. Doing so meant that the plugin:typescript-eslint/recommended preset config would lint against them by default.

The drawback of linting against those types by default was that nuanced types such as object and {} went through the same limited configuration channels as more straightforward types like Function. {} in particular has nuance of when it should be used -- which is not describable in a rule configuration format.

As of typescript-eslint v8, the old @typescript-eslint/ban-types rule has now been split into several more targeted rules. Those rules each capture one of the targeted areas of the now-deprecated @ytpescript-eslint/ban-types rule. By splitting into several rules, each has more specific, user-friendly configuration options and documentation pages.

Empty Object Types​

@typescript-eslint/no-empty-object-type is the new rule for banning the built-in {} type in confusing locations. The {}, or "empty object" type in TypeScript is a common source of confusion for developers unfamiliar with TypeScript's structural typing. These developers think {} represents "an object with no properties", however {} represents any non-nullish value. This means that it can represent any object with 0 or more properties or even primitives like strings, numbers, and booleans:

let anyNonNullishValue: {} = 'Intentionally allowed by TypeScript.';

Often, developers writing {} actually mean either:

• object: representing any object value
• unknown: representing any value at all, including null and undefined

In other words, the "empty object" type {} really means "any value that is defined". That includes arrays, class instances, functions, and primitives such as string and symbol. The word "object" in its name is a bit of a misnomer.

{} empty objects are permissible in a few edge cases, most commonly:

• Intersection constituents (e.g. types like TypeScript's type NonNullable<T> = T & {})
• Interfaces that extend from multiple other interfaces and add no fields of their own

Those cases could not be described with the old @typescript-eslint/ban-types format. Now, they are encoded as exemptions in the new @typescript-eslint/no-empty-object-type rule.

Function Types​

@typescript-eslint/no-unsafe-function-type is the new rule for banning the built-in Function type. The built-in Function type is an overly permissive way to describe a function. It allows being called with any number of arguments and returns type any.

const anyFunction: Function = (arg: boolean) => {};

anyFunction(); // Ok
anyFunction(123); // Ok
anyFunction('abc'); // Ok

const numberValue: number = anyFunction(); // Ok
const stringValue: string = anyFunction(); // Ok

Instead of using Function, code should generally specify function parameters and return types in types. Common cases and more examples are noted in the new @typescript-eslint/no-unsafe-function-type rule's documentation.

Primitive Wrapper Types​

@typescript-eslint/no-wrapper-object-types is the new rule for banning Object and built-in class wrappers such as Boolean and Number. TypeScript defines uppercase "wrapper" object types corresponding to each of JavaScript's primitive data types and equivalent wrapper classes: boolean/Boolean, number/Number, and so on.

let myNumber: Number;

myNumber = 0; // Ok
myNumber = Number(0); // Ok

let myObject: Object = 'allowed by TypeScript'; // Ok

Due to the quirks of TypeScript's structural typing, the corresponding primitives are also assignable to these uppercase types, since they have the same "shape". Instances of the uppercase class types also have surprisingly different behaviors at runtime, including always being truthy (even for values like new Boolean(false)) and being compared by reference (new String("a") !== new String("a")).

Instead of using uppercase wrapper object types, code should generally stick with lower-case primitive types. Common cases and more examples are noted in the new @typescript-eslint/no-wrapper-object-types rule's documentation.

User-Defined Type Bans​

@typescript-eslint/no-restricted-types is the new rule for banning a configurable list of type names. It acts similarly to the old ban-types rule:

• It defines no types by default: i.e. it must be configured to be useful
• It allows specifying types to ban, along with optional messages to display

As with @typescript-eslint/ban-types, @typescript-eslint/no-restricted-types additionally allows specifying auto-fixes to replace types with. The new rule also allows specifying suggestions to surface in editors, for cases when the fix isn't known to be reliable.

Here's an example of configuring the new rule to ban a deprecated API, with a custom message and two suggestions:

{
  "@typescript-eslint/no-restricted-types": [
    "error",
    {
      "types": {
        "DeprecatedOldAPI": {
          "message": "Use either NewAPIOne or NewAPITwo instead",
          "suggest": ["NewAPIOne", "NewAPITwo"],
        },
      },
    },
  ],
}

By acting as a purely user-configured rule, @typescript-eslint/no-restricted-types's behavior falls in line with core ESLint rules like no-restricted-imports and no-restricted-syntax.

See the new @typescript-eslint/no-restricted-types rule's documentation for more information on how to configure it.

Closing Thoughts​

We'd like to give a big thanks to all the users who gave feedback on the old @typescript-eslint/ban-types rule. In particular, we'd like to thank Ryan Cavanaugh from the TypeScript team for advising on the rule's design (and for dealing with users frequently sending issues to TypeScript itself on what was actually an overly aggressive lint rule).

Supporting typescript-eslint​

If you enjoyed this blog post and/or use typescript-eslint, please consider supporting us on Open Collective. We're a small volunteer team and could use your support to make the ESLint experience on TypeScript great. Thanks! 💖

Typed linting hasn't always been straightforward to configure or performant at runtime. We've seen users have to manage separate tsconfig.eslint.json files to enable typed linting — sometimes with different compiler options than the rest of the project. Not ideal.

In typescript-eslint 8.0, we stabilized a parserOptions.projectService option that uses more powerful, streamlined TypeScript APIs than before. The "Project Service" brings several benefits:

• ✍️ Configuration: simpler ESLint configs for typed linting with no ESLint-specific TSConfig files
• 🧠 Predictability: uses the same type information services as editors, including more reliability
• 🚀 Scalability: supporting TypeScript project references for larger repositories (i.e. monorepos)

This blog post will cover how parserOptions.projectService simplifies configurations and aligns linting type information to what editors such as VS Code run with.

Introducing the Project Service​

Back in Relative TSConfig Projects with parserOptions.project = true > Project Services, we'd mentioned a replacement for parserOptions.project:

The downside of having users specify parserOptions.project at all is that @typescript-eslint/parser needs manual logic to create TypeScript Programs and associate them with linted files. Manual Program creation logic comes with a few issues: ...

We're working on an option to instead call the same TypeScript "Project Service" APIs that editors such as VS Code use to create Programs for us instead. Project Services will automatically detect the TSConfig for each file (like project: true), and will also allow type information to be computed for JavaScript files without the allowJs compiler option (unlike project: true).

Following a year of discussion and beta testing in typescript-eslint v6 and v7, we believe the new Project Service API is ready to be used by real-world projects. We therefore promoted the parserOptions.EXPERIMENTAL_useProjectService option to the stable name parserOptions.projectService in typescript-eslint v8.

Configuration​

You can change over to the new Project Service API by replacing project with projectService in your ESLint configuration:

export default tseslint.config({
  // ...
  languageOptions: {
    parserOptions: {
      project: true,
      projectService: true,
      tsconfigRootDir: import.meta.dirname,
    },
  },
  // ...
});

module.exports = {
  // ...
  parser: '@typescript-eslint/parser',
  parserOptions: {
    project: true,
    projectService: true,
    tsconfigRootDir: __dirname,
  },
  // ...
};

That's it!

Other settings, including how you run ESLint and configure rules, should work the same.

Additional Files​

One long-standing pain point of typed linting was enabling typed linting for files not included in the project's tsconfig.json. Common solutions in the traditional Program API were to either skip typed linting for those files or to create a tsconfig.eslint.json enabling the allowJs compiler option.

The new Project Service API allows for a configuration object specifying allowDefaultProject: a glob of "out-of-project" files to lint with type information. That means you can lint those files without any new configuration files or TypeScript compiler options!

For example, the following config solves the common case of projects that have root-level files like eslint.config.js or vitest.config.ts:

export default tseslint.config({
  // ...
  languageOptions: {
    parserOptions: {
      projectService: {
        allowDefaultProject: ['*.js'],
      },
      tsconfigRootDir: import.meta.dirname,
    },
  },
  // ...
});

module.exports = {
  // ...
  parser: '@typescript-eslint/parser',
  parserOptions: {
    projectService: {
      allowDefaultProject: ['*.js'],
      tsconfigRootDir: __dirname,
    },
  },
  // ...
};

This means most projects should be able to remove all tsconfig.eslint.json files! 🥳

Predictability​

We've found configuring tsconfig.eslint.json files to be a common source of confusion with the traditional Program APIs. They can result in the type information used for linting accidentally being different from the type information used for type checking. Unifying TypeScript configurations to the same tsconfig.json file(s) altogether avoids potential divergent types.

Another benefit of using the new Project Service API is that typed linting requires no additional work in typescript-eslint for more difficult uses of ESLint and/or TypeScript. We sometimes had to de-optimize the traditional Program API to support use cases:

• CLI --fix mode would lose type information after the first pass (#9577)
• Extra file extensions such as .svelte and .vue were not supported at all (#9504)

The new Project Service API does not suffer from these issues. It supports extra file extensions out-of-the-box and does not slow down when used with ESLint's --fix.

Scalability​

TypeScript's project references are how many larger projects, in particular monorepos, scale TypeScript type checking. They allow delineating discrete projects with their own tsconfig.json files and annotating which projects depend on which other projects. TypeScript is able to cache type information and only recheck projects that have changed in builds based on those project references.

The traditional parserOptions.project API did not support project references for typed linting. We had experimented with adding support, but using the manual built-in TypeScript APIs would have been a significant maintenance investment with an unclear payoff.

The new Project Service API does support project references out-of-the-box. This is a huge win for monorepos, as it means you can lint all of your projects with type information without needing to create a separate tsconfig.eslint.json file for each project.

Performance​

Supporting project references allows the new Project Service API to be significantly faster than the traditional parserOptions.project API in many monorepo cases. We've observed improvements for typed linting speed in real-world repositories ^{1 2 3}. For smaller projects, the performance of the new Project Service API is similar to the traditional parserOptions.project API.

When we first started working with the new project service API, it outperformed equivalent parserOptions.project setups by ~10-15%. Since then, we have observed regressions in performance that have brought it down in some cases to be slightly slower.

We believe the new Project Service API should be faster than the traditional API, and are treating the lack of significant improvement as a bug. See ⚡ Performance: parserOptions.projectService sometimes no longer outperforms parserOptions.project for more information.

Next Steps​

The new Project Service API is available in typescript-eslint v8.0.0 and later. We've been using it in our monorepo for over a year and have been thrilled to see many community repositories adopt it as well.

Giving Feedback​

We'd love to hear from you on how this option works for you. Does it live up to what we've promised, and/or does it have bugs we haven't fixed yet? Please do send us GitHub issues for any bugs you encounter or suggestions for how to improve the API.

The typescript-eslint Discord is a great place to ask questions and engage with us more casually. For support in onboarding, feel free to ask in its #help channel. We'd be happy to help you try out parserOptions.projectService and learn more about how you use typescript-eslint.

Long Term Vision​

The new Project Service API is a great step towards making typed linting easier and more straightforward to configure. Our priority for the next year will be to improve the new Project Service API so that it works in all places the traditional Program API does. We won't remove the traditional project program behavior unless and until the new Project Service API is able to fully replace it.

As of typescript-eslint@8.33.0, we've also extracted most of the Project Service code into a standalone @typescript-eslint/project-service package. It has no dependencies on ESLint and is designed to be usable for any linter to enable TypeScript's Project Service API for typed linting. See Packages > Project Service for more details.

We're also looking forward to investigating support for TypeScript's 10x faster Go port. Abstracting configuration details into the Project Service API means it will be much easier for typescript-eslint to support typed linting using "tsgo" without any additional user configuration.

So, please, try out the new Project Service API. We're excited to hear how it works for you and what we can do to improve it. 💜

Supporting typescript-eslint​

If you enjoyed this blog post and/or use typescript-eslint, please consider supporting us on Open Collective. We're a small volunteer team and could use your support to make the ESLint experience on TypeScript great. Thanks! 💖

typescript-eslint includes several lint rules that help prevent unsafe practices around the any type. These rules flag uses of any or code patterns that sneakily introduce it.

In this blog post, we'll show you those lint rules and several other handy ways to prevent anys from sneaking into your code.

noImplicitAny Isn't Enough​

TypeScript includes a noImplicitAny flag to report when a better type than any can't be inferred for a value. noImplicitAny is part of its family of strict compiler options and is generally recommended for all projects.

However, even with noImplicitAny enabled, the any type can easily be introduced into codebases. noImplicitAny doesn't prevent developers from explicitly writing the any type in type type annotations. Some built-in APIs such as JSON.stringify and types such as Function can introduce the any type without triggering noImplicitAny.

Enabling noImplicitAny is a great first step towards better project type safety, but it's not enough to prevent anys altogether.

Banning Unsafe Types​

The first line of defense against any for many repositories is adding lint rules that report on explicitly written unsafe types. Developers can always disable ESLint rules with inline comments, so this isn't guaranteed to prevent explicit anys from popping up. But these lint rules put an immediate restriction on unsafe types -- and help guide towards better alternatives.

Banning Explicit anys​

@typescript-eslint/no-explicit-any reports on any instance of the any type written in your source code. Doing so helps prevent developers from using any instead of a more safe type.

Take the following unsafe declaration of friend: any in a greet function. Because its friend parameter is typed as any instead of string, TypeScript won't report a type error on a call that provides another type. @typescript-eslint/no-explicit-any would report on that any:

function greet(friend: any) {
  //                   ~~~
  // eslint(@typescript-eslint/no-explicit-any):
  // Unexpected any. Specify a different type.
  console.log(`Hello, ${friend.toUpperCase()}!`);
}

greet('Lazlo'); // Ok

greet({ name: 'Nadya' }); // Should be a type error, but isn't

Instead of any, it would have been more type safe to give friend the more precise type string.

Prefer unknown​

If you have data that is of an unknown type, instead of describing it with the unsafe any type, prefer the safer unknown instead. unknown is almost always preferable because it doesn't allow using the value in any arbitrary, potentially unsafe way.

@typescript-eslint/no-explicit-any's rule reports include a suggestion fixer that switches the explicit any to unknown.

Banning Function​

@typescript-eslint/no-unsafe-function-type reports on any instance of the built-in Function type written in source code. Function is a loose, unsafe type: it allows being called with any number of arguments and returns type any.

Take the following version of greet that takes in a function for its parameter. Function doesn't describe any parameter or return types, so TypeScript can't know what types it's meant to take in or return. @typescript-eslint/no-unsafe-function-type would report on that Function:

function greet(getFriend: Function) {
  //                      ~~~~~~~~
  // eslint(@typescript-eslint/no-unsafe-function-type):
  // The `Function` type accepts any function-like value.
  // Prefer explicitly defining any function parameters and return type.
  console.log(`Hello, ${getFriend().toUpperCase()}!`);
}

greet(() => 'Lazlo'); // Ok

greet(() => ({ name: 'Nadya' })); // Should be a type error, but isn't

Instead of Function, it would have been more type safe to give getFriend the more precise type () => string.

Enforcing unknown for Caught Exceptions​

There is no way to indicate what types functions may throw in TypeScript, due to the highly dynamic nature of JavaScript¹. Therefore, TypeScript treats all caught values as any by default. TypeScript's useUnknownInCatchVariables changes catch block variables to have the more appropriate unknown type, but no compiler option equivalent exists for Promise rejections' .catch() method.

@typescript-eslint/use-unknown-in-catch-callback-variable enforces always using the unknown type for the parameter of a Promise rejection callback.

For example, given the following code, TypeScript would not report a type error, but the lint rule would report:

function rejectWith(value: string) {
  return Promise.reject(value);
}

rejectWith('Nandor').catch(error => {
  //                       ~~~~~
  // eslint(@typescript-eslint/use-unknown-in-catch-callback-variable):
  // Prefer the safe `: unknown` for a `catch` callback variable.

  console.log(error.message); // Should be a type error, but isn't
});

Had the error been given a : unknown type, TypeScript would be able to report on error.message as being unsafe.

Banning Usage of Unsafe Types​

Once an any type exists in code, it is "infectious": it can turn the types of values based on it into more anys.

typescript-eslint includes a collection of rules that flag code patterns which make use of any's unsafe, viral nature. Each of the following rules reports on a specific use of any.

• @typescript-eslint/no-unsafe-argument reports on passing an any typed value to a function call
• @typescript-eslint/no-unsafe-assignment reports on assigning an any typed value to a property or variable
• @typescript-eslint/no-unsafe-call reports on calling an any typed value like a function
• @typescript-eslint/no-unsafe-member-access reports on accessing members of any value typed as any
• @typescript-eslint/no-unsafe-return reports on returning a value typed as any from a function

For example, this parseData function violates several of those lint rules by creating a shape value of type any and not validating its type before using it:

export interface Shape {
  label: string;
  value: number;
}

export function parseShapeFromData(raw: string): Shape {
  const shape = JSON.parse(raw);
  //    ~~~~~~~~~~~~~~~~~~~~~~~
  // eslint(@typescript-eslint/no-unsafe-assignment):
  // Unsafe assignment of an `any` value.

  console.log('Making a shape with value:', shape.value);
  //                                              ~~~~~
  // eslint(@typescript-eslint/no-unsafe-member-access):
  // Unsafe member access .value of an `any` value.

  return shape;
  // eslint(@typescript-eslint/no-unsafe-return):
  // Unsafe return of an `any` value.
}

Had the parseShapeFromData function included checks on the type of the shape value or used a schema validation library such as Zod, it would be informed at runtime if its raw string didn't create the expected Shape.

Put together, the @typescript-eslint/no-unusafe-* rules around any safety provide a comprehensive suite of checks that can flag most accidental uses of any across a codebase. We highly recommend using them alongside TypeScript's noImplicitAny compiler option.

Additional Helpers​

Disabling TypeScript Suppressions​

The any type is not the only way to bypass TypeScript's type system. Developers are also able to use inline TypeScript directives: // @ts-expect-error and // @ts-ignore. Those inline comment directives cause TypeScript to ignore type errors on a line. Disabling TypeScript on a per-line basis can sometimes be necessary in rare cases, but is always unsafe and should not be part of your standard toolkit.

@typescript-eslint/ban-comment can be used to report on cases where developers use TypeScript comment directives. By default, the rule:

• Prohibits all @ts-ignore and @ts-nocheck comment directives
• Prohibits @ts-expect-error directives unless they have an explanatory comment description
• Requires explanatory comment descriptions to contain at least 3 characters

For example, suppose "@example/package" exports a processString function that should take in a string but whose types incorrectly indicate take in a number. A // @ts-expect-error comment could be used to tell TypeScript to ignore the line:

import { processString } from '@example/package';

// @ts-ignore
processString('New York City');

import { processString } from '@example/package';

// @ts-expect-error -- Pending updating the processString types. See GH-1234.
processString('New York City');

Once the types for @example/package are fixed to no longer produce a type error, the comment directive will itself produce a type error asking to delete itself.

ESLint Comments Plugin​

ESLint includes its own inline comment directives separate from TypeScript's. // eslint-disable, // eslint-disable-next-line, and other inline ESLint config comments can suppress lint rules — including those mentioned in this post. Suppressing ESLint rules can also be necessary in cases where the rule and/or TypeScript's type system have misunderstand your code.

If you must use ESLint comment directives, we recommend utilizing @eslint-community/eslint-plugin-eslint-comments. The plugin's recommended preset enables rules that enforce best practices around ESLint comment directives, including:

• @eslint-community/eslint-comments/disable-enable-pair: to prevent accidentally disabling rules for the rest of a file, rather than on specific lines
• @eslint-community/eslint-comments/no-unlimited-disable: to prevent accidentally disabling all ESLint rules, rather than specific ones
• @eslint-community/eslint-comments/require-description: to require comments explaining why directives are necessary

For example, suppose the type of an imported variable is temporarily any pending some soon-to-be-completed refactoring. It might be reasonable to include an ESLint disable comment to suppress a lint rule reporting on the any. That comment should ideally include an explanation and link to the pending task, so developers know it's not normal to disable lint rules without good reason:

import { processString } from '@example/package';

// eslint-disable-next-line @typescript-eslint/no-unsafe-call
processString('New York City');

import { processString } from '@example/package';

// Pending GH-1234: will soon not be any.
// eslint-disable-next-line @typescript-eslint/no-unsafe-call
processString('New York City');

Once the types for @example/package are fixed to no longer produce an any, running ESLint with reportUnusedDisableDirectives option will produce a lint report asking to remove the comment directive.

ts-reset​

Some sources of any come from built-in global types provided by TypeScript. JSON.parse(), .json(), and Storage properties are all typed as any by default in TypeScript. TypeScript keeps any in the types for legacy support reasons².

The ts-reset library switches those global type definitions to safer equivalents. It switches the anys in those built-in types to unknown.

With ts-reset, the following data variable would switch from being type any to unknown:

const data = JSON.parse(`"clearly-a-string"`);
//    ^? any (without ts-reset)
//    ^? unknown (with ts-reset)

console.log(data.some.property.that.does.not.exist);

Note that ts-reset applies globally, so it should only be used in application code.

Next Steps​

We highly recommend using at least the tseslint.configs.recommendedTypeChecked preset in your ESLint configuration. It enables the no-explicit-any and no-unsafe-* lint rules mentioned in this blog post, as well as a large set of other rules that help enforce type safety and TypeScript best practices.

If you're interested in achieving stronger type safety with more strict linting, consider upgrading to the tseslint.configs.strictTypeChecked preset. It includes all the recommended rules, as well as use-unknown-in-catch-callback-variable and other rules that enforce more strict type safety and TypeScript best practices.

In this blog post, we'll give a high-level overview of how linting with type information works, why it's so much more powerful than traditional linting, and some of the useful rules you can enable that use it.

Recap: Type Information?​

Traditional JavaScript lint rules operate on one file at a time. They look at a description of code in each file and report complaints if that file seems to contain bad practices. That description is called an Abstract Syntax Tree, or AST.

Each file's AST contains only information for that file, not any other files. Lint rules that rely only on the file's AST don't have a way to understand code imported from other files, such as in ESM import statements. Not being able to understand code from other files severely limits lint rules.

As an example, suppose you enable a lint rule like @typescript-eslint/no-deprecated to prevent calling to code with a @deprecated JSDoc. Using just the following file's AST, the lint rule would have no way of knowing whether work is deprecated:

import { work } from './worker';

// Is this safe? Does calling work violate any rules? We don't know!
work();

Type information refers to the information a type checker such as TypeScript generates to understand your code. Type checkers read code, determine what types each value may be, and store that "type information". TypeScript and tools that call to TypeScript's APIs can then use that type information to understand the project's code.

In the earlier example, type information would be able to inform a lint rule running in index.ts that the work import resolves to a function in another file:

/** @deprecated - Don't do this! */
export function work() {
  // ...
}

...which would allow the lint rule to report a complaint that the work() call is to a function marked as @deprecated.

typescript-eslint allows lint rules to retrieve type information using TypeScript's APIs. In doing so, they can even make decisions on linted files using information outside each individual file.

Common Uses for Typed Linting​

Cross-file type information is a powerful addition to lint rules. Knowing the types of pieces of your code allows lint rules to flag for risky behavior specific to certain types. The following sections show several of the most common uses for lint rules that rely on type information.

Unsafe anys​

The @typescript-eslint/no-unsafe-* family of rules checks for risky uses of any typed values. This is useful because the any type can easily slip into code and reduce type safety, despite being allowed by the TypeScript type checker.

For example, the following code that logs a member of an object parsed from a string produces no type errors in type checking. JSON.parse() returns any, and arbitrary property accesses are allowed on values of type any.

However, @typescript-eslint/no-unsafe-member-access would report [key] might not be a property on the object:

function getDataKey(rawData: string, key: string): string {
  return JSON.parse(rawData)[key];
  //                        ~~~~~
  // Unsafe member access [key] on an `any` value.
  // eslint(@typescript-eslint/no-unsafe-member-access)
}

The lint rule is right to report. Calls to the getDataKey function can return a value that's not a string, despite the function's explicit return type annotation. That can lead to unexpected behavior at runtime:

console.log(getDataKey(`{ "blue": "cheese" }`, 'bleu').toUpperCase());
// Uncaught TypeError: Cannot read properties of undefined (reading 'toUpperCase')

Without type information to indicate the types of JSON.parse and key, there would have been no way to determine that the [key] member access was unsafe.

Method Call Scoping​

Runtime crashes caused by misuses of typed code are possible even with no anys.

For example, class method functions don't preserve their class scope when passed as standalone variables ("unbound"). TypeScript still allows them to be called without the proper this scope.

The global localStorage object in browsers has several properties that must be called with a this bound to localStorage. The @typescript-eslint/unbound-method lint rule can report on unsafe references to those properties, such as accessing getItem:

const { getItem } = localStorage;
//      ~~~~~~~
// Avoid referencing unbound methods which may cause unintentional scoping of `this`.
// eslint(@typescript-eslint/unbound-method)

That's useful because calls to getItem that aren't bound to localStorage cause an exception at runtime:

getItem('...');
// Uncaught TypeError: Illegal invocation

Without type information to indicate the types of localStorage and its getItem property, there would have been no reliable way to determine that the const { getItem } access was unsafe.

Async Race Conditions​

Even if your code is 100% typed, has no anys, and doesn't misuse scopes, it's still possible to have bugs that can only easily be detected by typed linting. Asynchronous code with Promises in particular can introduce subtle issues that are completely type-safe.

Suppose your code is meant to run an asynchronous readFromCache function before reading from the file system:

import { fs } from 'node:fs/promises';
import { readFromCache } from './caching';

const filePath = './data.json';

readFromCache(filePath);

await fs.rm(filePath);

Do you see the potential bug?

If readFromCache is asynchronous (returns a Promise), then calling it and not awaiting its returned Promise could lead to race conditions in code. Its asynchronous or delayed logic might not get to reading from the filePath before fs.rm(filePath) runs.

This is commonly referred to as a "floating" Promise: one that is created but not appropriately handled. The @typescript-eslint/no-floating-promises lint rule would report on that floating Promise:

readFromCache(filePath);
// Promises must be awaited, end with a call to .catch, end with a call to .then
// with a rejection handler or be explicitly marked as ignored with the `void` operator.
// eslint(@typescript-eslint/no-floating-promises

...and can give an editor suggestion to add a missing await:

- readFromCache(filePath);
+ await readFromCache(filePath);

Determining whether code is creating a floating Promise is only possible when the types of code are known. Otherwise, lint rules would have no way of knowing which imports from other files could potentially create a Promise that needs to be handled.

Custom Rules​

Typed linting isn't restricted to just typescript-eslint rules. It can be used in community ESLint plugins, as well as custom rules specific to your project.

One common example used by teams is to codemod from a deprecated API to its replacement. Typed linting is often necessary to determine which pieces of code call to the old API.

As an example, consider the following fetch() POST call that sends data to an intake API. Suppose the intake endpoint is migrating from sending [string, string] tuples to sending key-value pairs. A typed lint rule could determine that the data is in the old format:

import { endpoints } from "~/api";

const rawData = ["key", "value"] as const;

await fetch(endpoints.intake, {
  data: JSON.stringify(rawData)
  //                   ~~~~~~~
  // Don't pass a tuple to endpoints.intake. Pass a key-value object instead.
  // eslint(@my-team/custom-rule)
  // ...
  method: "POST",
});

...and provide a code fix to automatically migrate to the new format:

import { endpoints } from "~/api";

const rawData = ["key", "value"] as const;

await fetch(endpoints.intake, {
- data: JSON.stringify(rawData)
+ data: JSON.stringify(Object.fromEntries(rawData))
  // ...
  method: "POST",
});

Knowing that the fetch() call was being sent to endpoints.intake and that the type of the data was a tuple takes typed linting.

That kind of migration codemod is one of the ways typed linting can be utilized for project- or team-specific rules. See Developers > Custom Rules for more documentation on building your own ESLint rules with typescript-eslint.

Enabling Typed Linting​

You can add typed linting to your ESLint configuration by following the steps in Linting with Type Information. We recommend doing so by enabling parserOptions.projectService:

import tseslint from 'typescript-eslint';

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.recommendedTypeChecked,
  {
    languageOptions: {
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname,
      },
    },
  },
);

typescript-eslint will then use TypeScript APIs behind-the-scenes, to, for each file being linted:

1. Determine the appropriate TSConfig dictating how to generate that file's type information
2. Make APIs available to lint rules to retrieve type information for the file

Lint rules that opt into type information will then be able to use those APIs when linting your code.

Drawbacks of Typed Linting​

Linting with type information comes with two drawbacks: configuration complexity and a performance penalty.

For configuring typed linting, parserOptions.projectService solves configuration difficulties for most projects. The more manual parserOptions.project is also available for more complex project setups. See Troubleshooting & FAQs > Typed Linting for details on common issues.

For performance, it is inevitable that typed linting will slow your linting down to roughly the speed of type checking your project. Typed lint rules call to the same TypeScript APIs as the command-line tsc. If linting your project is much slower than running tsc on the same set of files, see Troubleshooting & FAQs > Typed Linting > Performance.

Final Thoughts​

In our experience, the additional bug catching and features added by typed linting are well worth the costs of configuration and performance. Typed linting allows lint rules to act with much greater confidence on a wider area of checking, including avoiding unsafe any uses, enforcing proper this scopes, and catching asynchronous code mishaps.

If you haven't yet tried out typed linting using the typescript-eslint rules mentioned in this blog post, we'd strongly recommend going through our Linting with Type Information guide.

Supporting typescript-eslint​

If you enjoyed this blog post and/or use typescript-eslint, please consider supporting us on Open Collective. We're a small volunteer team and could use your support to make the ESLint experience on TypeScript great. Thanks! 💖

We'd previously blogged about v8 in Announcing typescript-eslint v8 Beta. This blog post contains much of the same information as that one, and includes the list of steps you'll need to take to upgrade.

Trying Out v8​

Whether you're new to linting your TypeScript code or a returning user, please do upgrade to the latest major version of typescript-eslint! V8 comes with a suite of quality-of-life improvements we think you'll appreciate.

As A New User​

If you don't yet use typescript-eslint, you can go through our configuration steps on the v8 Getting Started docs. It'll walk you through setting up typescript-eslint in a project.

As An Existing User​

If you already use typescript-eslint, you'll need to first replace your package's previous versions with @8:

npm i typescript-eslint@8 --save-dev

npm i @typescript-eslint/eslint-plugin@8 @typescript-eslint/parser@8 --save-dev

We highly recommend then basing your ESLint configuration on the reworked typescript-eslint recommended configurations — especially if it's been a while since you've reworked your linter config.

User-Facing Changes​

These are the changes that users of typescript-eslint —generally, any developer running ESLint on TypeScript code— should pay attention to when upgrading typescript-eslint from v7 to v8.

ESLint v9 Support​

typescript-eslint v8 ships with full support for ESLint v9.

typescript-eslint v7 was our first version that supported ESLint's new "flat" config file format, which was already available in ESLint v8. ESLint v9 still supports ESLint's older legacy config file format so our tooling does as well. However, ESLint v9 also includes a set of breaking changes that we added support for in typescript-eslint v8. See the ESLint v9 release blog post for more details.

Project Service​

The biggest new feature added in this version is the stability of our new "project service". In short, the project service is a new way to enable typed linting that is generally easier to configure and faster at runtime than our previous offerings. It's been experimentally available since v6.1.0 under the name EXPERIMENTAL_useProjectService; now, we've renamed it to projectService.

You can use the new project service in your configuration instead of the previous parserOptions.project:

import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.recommendedTypeChecked,
  {
    languageOptions: {
      parserOptions: {
        project: true,
        projectService: true,
        tsconfigRootDir: import.meta.dirname,
      },
    },
  },
);

The project service will automatically find the closest tsconfig.json for each file (like project: true). It also allows enabling typed linting for files not explicitly included in a tsconfig.json. This should remove the need for custom tsconfig.eslint.json files to lint files like eslint.config.mjs!

Typed linting for out-of-project files can be done by specifying two properties of a parserOptions.projectService object:

• allowDefaultProject: a glob of a small number of out-of-project files to enable a slower default project on
• defaultProject: path to a TypeScript configuration file to use for the slower default project

import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.recommendedTypeChecked,
  {
    languageOptions: {
      parserOptions: {
        project: ['packages/*/tsconfig.json', 'tsconfig.eslint.json'],
        projectService: {
          allowDefaultProject: ['*.js'],
          defaultProject: 'tsconfig.json',
        },
        tsconfigRootDir: import.meta.dirname,
      },
    },
  },
);

Internally, the project service uses the same TypeScript APIs that editors such as VS Code use. Doing so should make it harder to accidentally configure different type information for ESLint than what you see in day-to-day editing.

We're thrilled to have the project service option promoted to stable in v8. We'll soon release a dedicated parserOptions blog post walking through the new option in more details. 🚀

Updated Configuration Rules​

Every new major version of typescript-eslint comes with changes to which rules are enabled in the preset configurations and with which options. See the table in Changes to configurations for 8.0.0 for more context on the changes.

Please do try out the new rule configurations presets and let us know in that discussion!

{
   '@typescript-eslint/ban-ts-comment': '...',
-  '@typescript-eslint/ban-types': '...',
   'no-array-constructor': '...',
   '@typescript-eslint/no-array-constructor': '...',
   '@typescript-eslint/no-duplicate-enum-values': '...',
+  '@typescript-eslint/no-empty-object-type': '...',
   '@typescript-eslint/no-explicit-any': '...',
   '@typescript-eslint/no-extra-non-null-assertion': '...',
-  'no-loss-of-precision': '...',
-  '@typescript-eslint/no-loss-of-precision': '...',
   '@typescript-eslint/no-misused-new': '...',
   '@typescript-eslint/no-namespace': '...',
   '@typescript-eslint/no-non-null-asserted-optional-chain': '...',
+  '@typescript-eslint/no-require-imports': '...',
   '@typescript-eslint/no-this-alias': '...',
   '@typescript-eslint/no-unnecessary-type-constraint': '...',
   '@typescript-eslint/no-unsafe-declaration-merging': '...',
+  '@typescript-eslint/no-unsafe-function-type': '...',
+  'no-unused-expressions': '...',
+  '@typescript-eslint/no-unused-expressions': '...',
   'no-unused-vars': '...',
   '@typescript-eslint/no-unused-vars': '...',
-  '@typescript-eslint/no-var-requires': '...',
+  '@typescript-eslint/no-wrapper-object-types': '...',
   '@typescript-eslint/prefer-as-const': '...',
+  '@typescript-eslint/prefer-namespace-keyword': '...',
   '@typescript-eslint/triple-slash-reference': '...',
}

{
   '@typescript-eslint/await-thenable': '...',
   '@typescript-eslint/ban-ts-comment': '...',
-  '@typescript-eslint/ban-types': '...',
   'no-array-constructor': '...',
   '@typescript-eslint/no-array-constructor': '...',
+  '@typescript-eslint/no-array-delete': '...',
   '@typescript-eslint/no-base-to-string': '...',
   '@typescript-eslint/no-duplicate-enum-values': '...',
   '@typescript-eslint/no-duplicate-type-constituents': '...',
+  '@typescript-eslint/no-empty-object-type': '...',
   '@typescript-eslint/no-explicit-any': '...',
   '@typescript-eslint/no-extra-non-null-assertion': '...',
   '@typescript-eslint/no-floating-promises': '...',
   '@typescript-eslint/no-for-in-array': '...',
   'no-implied-eval': '...',
   '@typescript-eslint/no-implied-eval': '...',
-  'no-loss-of-precision': '...',
-  '@typescript-eslint/no-loss-of-precision': '...',
   '@typescript-eslint/no-misused-new': '...',
   '@typescript-eslint/no-misused-promises': '...',
   '@typescript-eslint/no-namespace': '...',
   '@typescript-eslint/no-non-null-asserted-optional-chain': '...',
   '@typescript-eslint/no-redundant-type-constituents': '...',
+  '@typescript-eslint/no-require-imports': '...',
   '@typescript-eslint/no-this-alias': '...',
+  'no-throw-literal': '...',
   '@typescript-eslint/no-unnecessary-type-assertion': '...',
   '@typescript-eslint/no-unnecessary-type-constraint': '...',
   '@typescript-eslint/no-unsafe-argument': '...',
   '@typescript-eslint/no-unsafe-assignment': '...',
   '@typescript-eslint/no-unsafe-call': '...',
   '@typescript-eslint/no-unsafe-declaration-merging': '...',
   '@typescript-eslint/no-unsafe-enum-comparison': '...',
+  '@typescript-eslint/no-unsafe-function-type': '...',
   '@typescript-eslint/no-unsafe-member-access': '...',
   '@typescript-eslint/no-unsafe-return': '...',
+  '@typescript-eslint/no-unsafe-unary-minus': '...',
+  'no-unused-expressions': '...',
+  '@typescript-eslint/no-unused-expressions': '...',
   'no-unused-vars': '...',
   '@typescript-eslint/no-unused-vars': '...',
-  '@typescript-eslint/no-var-requires': '...',
+  '@typescript-eslint/no-wrapper-object-types': '...',
+  '@typescript-eslint/only-throw-error': '...',
   '@typescript-eslint/prefer-as-const': '...',
+  '@typescript-eslint/prefer-namespace-keyword': '...',
+  'prefer-promise-reject-errors': '...',
+  '@typescript-eslint/prefer-promise-reject-errors': '...',
   'require-await': '...',
   '@typescript-eslint/require-await': '...',
   '@typescript-eslint/restrict-plus-operands': '...',
   '@typescript-eslint/restrict-template-expressions': '...',
   '@typescript-eslint/triple-slash-reference': '...',
   '@typescript-eslint/unbound-method': '...',
}

{
   '@typescript-eslint/ban-ts-comment': '...',
-  '@typescript-eslint/ban-types': '...',
   'no-array-constructor': '...',
   '@typescript-eslint/no-array-constructor': '...',
   '@typescript-eslint/no-duplicate-enum-values': '...',
   '@typescript-eslint/no-dynamic-delete': '...',
+  '@typescript-eslint/no-empty-object-type': '...',
   '@typescript-eslint/no-explicit-any': '...',
   '@typescript-eslint/no-extra-non-null-assertion': '...',
   '@typescript-eslint/no-extraneous-class': '...',
   '@typescript-eslint/no-invalid-void-type': '...',
-  'no-loss-of-precision': '...',
-  '@typescript-eslint/no-loss-of-precision': '...',
   '@typescript-eslint/no-misused-new': '...',
   '@typescript-eslint/no-namespace': '...',
   '@typescript-eslint/no-non-null-asserted-nullish-coalescing': '...',
   '@typescript-eslint/no-non-null-asserted-optional-chain': '...',
   '@typescript-eslint/no-non-null-assertion': '...',
+  '@typescript-eslint/no-require-imports': '...',
   '@typescript-eslint/no-this-alias': '...',
   '@typescript-eslint/no-unnecessary-type-constraint': '...',
   '@typescript-eslint/no-unsafe-declaration-merging': '...',
+  '@typescript-eslint/no-unsafe-function-type': '...',
+  'no-unused-expressions': '...',
+  '@typescript-eslint/no-unused-expressions': '...',
   'no-unused-vars': '...',
   '@typescript-eslint/no-unused-vars': '...',
   'no-useless-constructor': '...',
   '@typescript-eslint/no-useless-constructor': '...',
-  '@typescript-eslint/no-var-requires': '...',
+  '@typescript-eslint/no-wrapper-object-types': '...',
   '@typescript-eslint/prefer-as-const': '...',
   '@typescript-eslint/prefer-literal-enum-member': '...',
+  '@typescript-eslint/prefer-namespace-keyword': '...',
   '@typescript-eslint/triple-slash-reference': '...',
   '@typescript-eslint/unified-signatures': '...',
}

{
   '@typescript-eslint/await-thenable': '...',
   '@typescript-eslint/ban-ts-comment': '...',
-  '@typescript-eslint/ban-types': '...',
   'no-array-constructor': '...',
   '@typescript-eslint/no-array-constructor': '...',
   '@typescript-eslint/no-array-delete': '...',
   '@typescript-eslint/no-base-to-string': '...',
   '@typescript-eslint/no-confusing-void-expression': '...',
   '@typescript-eslint/no-duplicate-enum-values': '...',
   '@typescript-eslint/no-duplicate-type-constituents': '...',
   '@typescript-eslint/no-dynamic-delete': '...',
+  '@typescript-eslint/no-empty-object-type': '...',
   '@typescript-eslint/no-explicit-any': '...',
   '@typescript-eslint/no-extra-non-null-assertion': '...',
   '@typescript-eslint/no-extraneous-class': '...',
   '@typescript-eslint/no-floating-promises': '...',
   '@typescript-eslint/no-for-in-array': '...',
   'no-implied-eval': '...',
   '@typescript-eslint/no-implied-eval': '...',
   '@typescript-eslint/no-invalid-void-type': '...',
-  'no-loss-of-precision': '...',
-  '@typescript-eslint/no-loss-of-precision': '...',
   '@typescript-eslint/no-meaningless-void-operator': '...',
   '@typescript-eslint/no-misused-new': '...',
   '@typescript-eslint/no-misused-promises': '...',
   '@typescript-eslint/no-mixed-enums': '...',
   '@typescript-eslint/no-namespace': '...',
   '@typescript-eslint/no-non-null-asserted-nullish-coalescing': '...',
   '@typescript-eslint/no-non-null-asserted-optional-chain': '...',
   '@typescript-eslint/no-non-null-assertion': '...',
   '@typescript-eslint/no-redundant-type-constituents': '...',
+  '@typescript-eslint/no-require-imports': '...',
+  'no-return-await': '...',
   '@typescript-eslint/no-this-alias': '...',
   'no-throw-literal': '...',
   '@typescript-eslint/no-unnecessary-boolean-literal-compare': '...',
   '@typescript-eslint/no-unnecessary-condition': '...',
   '@typescript-eslint/no-unnecessary-template-expression': '...',
   '@typescript-eslint/no-unnecessary-type-arguments': '...',
   '@typescript-eslint/no-unnecessary-type-assertion': '...',
   '@typescript-eslint/no-unnecessary-type-constraint': '...',
+  '@typescript-eslint/no-unnecessary-type-parameters': '...',
   '@typescript-eslint/no-unsafe-argument': '...',
   '@typescript-eslint/no-unsafe-assignment': '...',
   '@typescript-eslint/no-unsafe-call': '...',
   '@typescript-eslint/no-unsafe-declaration-merging': '...',
   '@typescript-eslint/no-unsafe-enum-comparison': '...',
+  '@typescript-eslint/no-unsafe-function-type': '...',
   '@typescript-eslint/no-unsafe-member-access': '...',
   '@typescript-eslint/no-unsafe-return': '...',
+  '@typescript-eslint/no-unsafe-unary-minus': '...',
+  'no-unused-expressions': '...',
+  '@typescript-eslint/no-unused-expressions': '...',
   'no-unused-vars': '...',
   '@typescript-eslint/no-unused-vars': '...',
   'no-useless-constructor': '...',
   '@typescript-eslint/no-useless-constructor': '...',
-  '@typescript-eslint/no-var-requires': '...',
+  '@typescript-eslint/no-wrapper-object-types': '...',
   '@typescript-eslint/only-throw-error': '...',
   '@typescript-eslint/prefer-as-const': '...',
-  '@typescript-eslint/prefer-includes': '...',
   '@typescript-eslint/prefer-literal-enum-member': '...',
+  '@typescript-eslint/prefer-namespace-keyword': '...',
   'prefer-promise-reject-errors': '...',
   '@typescript-eslint/prefer-promise-reject-errors': '...',
   '@typescript-eslint/prefer-reduce-type-parameter': '...',
   '@typescript-eslint/prefer-return-this-type': '...',
   'require-await': '...',
   '@typescript-eslint/require-await': '...',
   '@typescript-eslint/restrict-plus-operands': '...',
   '@typescript-eslint/restrict-template-expressions': '...',
+  '@typescript-eslint/return-await': '...',
   '@typescript-eslint/triple-slash-reference': '...',
   '@typescript-eslint/unbound-method': '...',
   '@typescript-eslint/unified-signatures': '...',
   '@typescript-eslint/use-unknown-in-catch-callback-variable': '...',
}

{
   '@typescript-eslint/adjacent-overload-signatures': '...',
   '@typescript-eslint/array-type': '...',
   '@typescript-eslint/ban-tslint-comment': '...',
   '@typescript-eslint/class-literal-property-style': '...',
   '@typescript-eslint/consistent-generic-constructors': '...',
   '@typescript-eslint/consistent-indexed-object-style': '...',
   '@typescript-eslint/consistent-type-assertions': '...',
   '@typescript-eslint/consistent-type-definitions': '...',
   '@typescript-eslint/no-confusing-non-null-assertion': '...',
   'no-empty-function': '...',
   '@typescript-eslint/no-empty-function': '...',
-  '@typescript-eslint/no-empty-interface': '...',
   '@typescript-eslint/no-inferrable-types': '...',
   '@typescript-eslint/prefer-for-of': '...',
   '@typescript-eslint/prefer-function-type': '...',
-  '@typescript-eslint/prefer-namespace-keyword': '...',
}

{
   '@typescript-eslint/adjacent-overload-signatures': '...',
   '@typescript-eslint/array-type': '...',
   '@typescript-eslint/ban-tslint-comment': '...',
   '@typescript-eslint/class-literal-property-style': '...',
   '@typescript-eslint/consistent-generic-constructors': '...',
   '@typescript-eslint/consistent-indexed-object-style': '...',
   '@typescript-eslint/consistent-type-assertions': '...',
   '@typescript-eslint/consistent-type-definitions': '...',
   'dot-notation': '...',
   '@typescript-eslint/dot-notation': '...',
   '@typescript-eslint/no-confusing-non-null-assertion': '...',
   'no-empty-function': '...',
   '@typescript-eslint/no-empty-function': '...',
-  '@typescript-eslint/no-empty-interface': '...',
   '@typescript-eslint/no-inferrable-types': '...',
   '@typescript-eslint/non-nullable-type-assertion-style': '...',
+  '@typescript-eslint/prefer-find': '...',
   '@typescript-eslint/prefer-for-of': '...',
   '@typescript-eslint/prefer-function-type': '...',
+  '@typescript-eslint/prefer-includes': '...',
-  '@typescript-eslint/prefer-namespace-keyword': '...',
   '@typescript-eslint/prefer-nullish-coalescing': '...',
   '@typescript-eslint/prefer-optional-chain': '...',
+  '@typescript-eslint/prefer-regexp-exec': '...',
   '@typescript-eslint/prefer-string-starts-ends-with': '...',
}

Rule Breaking Changes​

Several rules are changed in significant enough ways to be considered breaking changes:

• Rules: Deprecate prefer-ts-expect-error in favor of ban-ts-comment
  • If you have @typescript-eslint/prefer-ts-expect-error manually enabled, remove that, and instead either use a recommended config or manually enable @typescript-eslint/ban-ts-comment.
• chore(eslint-plugin): deprecate no-var-requires in favor of no-require-imports
  • If you have @typescript-eslint/no-var-requires manually enabled, remove that, and instead either use a recommended config or manually enable @typescript-eslint/no-require-imports.
• feat(eslint-plugin): remove deprecated no-throw-literal rule
  • If you have @typescript-eslint/no-throw-literal manually enabled, remove that, and instead either use a recommended config or manually enable @typescript-eslint/only-throw-error.
• feat(eslint-plugin): [no-useless-template-literals] rename to no-useless-template-expression (deprecate no-useless-template-literals) and fix: no-useless-template-expression -> no-unnecessary-template-expression
  • Find-and-replace text from no-useless-template-literals to no-unnecessary-template-expression
• feat(eslint-plugin): deprecate no-loss-of-precision extension rule
  • If you have @typescript-eslint/no-loss-of-precision manually enabled, replace it with the base rule no-loss-of-precision.
• feat(eslint-plugin): remove formatting/layout rules
  • If you're using any of the old deprecated formatting rules, see eslint.style for their new equivalents
• feat(eslint-plugin): [prefer-nullish-coalescing] change ignoreConditionalTests default to true
  • If you want to have the rule check conditional tests, set its ignoreConditionalTests option to false in your ESLint config
• feat(eslint-plugin): [no-unused-vars] align catch behavior to ESLint 9
  • If you want @typescript-eslint/no-unused-vars to ignore caught errors, enable its caughtErrors option to 'none' in your ESLint config

Replacement of ban-types​

@typescript-eslint/ban-types has long been one of the more controversial rules in typescript-eslint. It served two purposes:

• Allowing users to ban a configurable list of types from being used in type annotations
• Banning confusing or dangerous built-in types such as Function and Number

Notably, ban-types banned the built-in {} ("empty object") type in TypeScript. The {} type is a common source of confusion for TypeScript developers because it matches any non-nullable value, including primitives like "".

Banning {} in ban-types was helpful to prevent developers from accidentally using it instead of a more safe type such as object. On the other hand, there are legitimate uses for {}, and banning it by default was harmful in those cases.

typescript-eslint v8 deletes the ban-types rule and replaces it with several more targeted rules:

• @typescript-eslint/no-restricted-types is the new rule for banning a configurable list of type names. It has no options enabled by default.
• @typescript-eslint/no-empty-object-type bans the built-in {} type in confusing locations.
• @typescript-eslint/no-unsafe-function-type bans the built-in Function type
• @typescript-eslint/no-wrapper-object-types bans Object and built-in class wrappers such as Number.

To migrate to the new rules:

• If you were disabling the ban on {}, consider enabling @typescript-eslint/no-empty-object-type, as it allows some cases of {} that were previously banned.
• If you were banning any configurable types lists, provide a similar configuration to no-restricted-types.
• If you have @typescript-eslint/ban-types manually enabled, it will no longer ban:
  • {}: use a recommended config or manually enable @typescript-eslint/no-empty-object-type.
  • Function: use a recommended config or manually enable @typescript-eslint/no-unsafe-function-type.
  • Number or other built-in uppercase types: use a recommended config or manually enable @typescript-eslint/no-wrapper-object-types.
• If you have @typescript-eslint/no-empty-interface manually enabled, remove that, and instead either use a recommended config or manually enable @typescript-eslint/no-empty-object-type.

For more details, see the issues and pull requests that split apart the ban-types rule:

• Enhancement: [ban-types] Split the ban into a separate, better-phrased rule
• feat(eslint-plugin): split no-empty-object-type out from ban-types and no-empty-interface
• Enhancement: [ban-types] Split into default-less no-restricted-types and more targeted type ban rule(s)
• feat(eslint-plugin): replace ban-types with no-restricted-types, no-unsafe-function-type, no-wrapper-object-types

Tooling Breaking Changes​

• fix(typescript-estree): enable dot globs for project by default
  • This will cause any parserOptions.project globs to match dot (.) directories. If you don't want to match them then use a more specific set of globs, or switch to parserOptions.projectService.
• feat(typescript-estree): remove slow deprecated and isolated programs
  • If you were still using parserOptions.DEPRECATED__createDefaultProgram, switch to parserOptions.projectService (recommended) or parserOptions.project.
• feat(typescript-estree): rename automaticSingleRunInference to disallowAutomaticSingleRunInference
  • We've updated the default to be an opt-out - meaning you no longer need to enable it:

    parserOptions: {
      automaticSingleRunInference: true,
      // ...
    }
    
• chore: bump minimum versions for v8
  • ESLint support range was changed from ^8.56.0 to ^8.57.0
  • Node.js support range was changed from ^18.18.0 || >=20.0.0 to ^18.18.0 || ^20.9.0 || >=21.1.0
  • TypeScript support range was changed from >=4.7.4 <5.5.0 to >=4.8.4 <5.5.0
• Parser: remove EXPERIMENTAL_useSourceOfProjectReferenceRedirect in favor of project service
  • We now recommend using the new parserOptions.projectService instead

Developer-Facing Changes​

typescript-eslint v8 comes with a suite of cleanups and improvements for developers using its Node.js APIs as well. If you author any ESLint plugins or other tools that interact with TypeScript syntax, then we recommend you try out typescript-eslint v8 soon. It includes some breaking changes that you may need to accommodate for.

AST Breaking Changes​

These changes are to the AST shapes generated by typescript-eslint when parsing code. If you author any ESLint rules that refer to the syntax mentioned by them, these are relevant to you.

• Enhancement: add strict parent types for nodes that have well-defined parents
  • This will help you remove some unnecessary conditions - we suggest using @typescript-eslint/no-unnecessary-condition to help find the unnecessary checks!
• feat(typescript-estree): split TSMappedType typeParameter into constraint and key
  • If your code handles mapped types, change from node.typeParameter.constraint to node.constraint and from node.typeParameter.name to node.key
• feat(ast-spec): remove deprecated type params
  • If you haven't already you must stop using those removed AST properties that were already marked as @deprecated
• fix(typescript-estree): add TSEnumBody node for TSEnumDeclaration body #8920
  • If your code handles enums, switch from node.members to node.body.members

Custom Rule meta.docs Types​

@typescript-eslint/utils has long exported a RuleCreator utility for making custom well-typed custom ESLint rules. That RuleCreator is used internally by @typescript-eslint/eslint-plugin — and in fact, up through typescript-eslint v7, it hardcoded the same types for rules' meta.docs as @typescript-eslint/eslint-plugin!

In typescript-eslint v8, we've made two changes to RuleCreator:

• Rule meta.docs by default only allows the properties defined in ESLint's Custom Rules > Rule Structure docs: description and url
• RuleCreator allows an optional type parameter to specify additional allowed properties

For example, this rule includes the common meta.docs.recommended property as a boolean:

interface MyPluginDocs {
  recommended: boolean;
}

const createRule = ESLintUtils.RuleCreator<MyPluginDocs>(
  name => `https://example.com/rule/${name}`,
);

createRule({
  // ...
  meta: {
    docs: {
      description: '...',
      recommended: true,
    },
    // ...
  },
});

See feat(utils): allow specifying additional rule meta.docs in RuleCreator for more details.

Flat Configuration RuleTester​

The RuleTester provided by @typescript-eslint/rule-tester is a fork of ESLint's RuleTester. In typescript-eslint v7 and earlier, RuleTester's constructor allowed providing legacy "eslintrc" options -- mirroring ESLint v8 and earlier. In typescript-eslint v8, RuleTester's constructor now instead allows providing new "flat" config options -- mirroring ESLint v9.

Per ESLint flat configs, any parser configurations you provide will need to be inside a languageOptions property:

import { RuleTester } from '@typescript-eslint/rule-tester

const ruleTester = new RuleTester({
  languageOptions: {
    parserOptions: {
      tsconfigRootDir: import.meta.dirname,
    },
  },
});

Any parser you provide will need to be the parser itself, rather than a string name of the package:

import { RuleTester } from '@typescript-eslint/rule-tester
import jsoncParser from "jsonc-eslint-parser";

const ruleTester = new RuleTester({
  languageOptions: {
    parser: jsoncParser,
    parser: "jsonc-eslint-parser",
  },
});

This change brings typescript-eslint's RuleTester in line with ESLint's RuleTester and flat config. In doing so, it changes two parserOptions defaults:

• ecmaVersion: from 5 to 'latest'
• sourceType: from 'script' to 'module'

If you were specifying either or both of those in your tests, you likely can now omit them:

import { RuleTester } from '@typescript-eslint/rule-tester

const ruleTester = new RuleTester();
const ruleTester = new RuleTester({
  parserOptions: {
    ecmaVersion: 2018,
    sourceType: 'module',
  },
});

For more details, see:

• ESLint > Migrate to 9.0.0 > FlatRuleTester is now RuleTester
• typescript-eslint > feat(rule-tester): switched to flat config

Support for multi-pass fixes in RuleTester​

One limitation of ESLint's RuleTester is that it is not possible to verify the individual applied fixes when a rule provides multiple rounds of fixes. ESLint's RuleTester applies only the first fix when there is conflict between two fixes.

In typescript-eslint v8, our RuleTester tries to apply all possible fixes for each test case.

If your rule tests had some test cases that required multi-pass fixes, you will see some test failures. To fix these failures, provide an array of strings for output which specifies the output after each fix pass.

import { RuleTester } from '@typescript-eslint/rule-tester';
import rule from '../src/rules/my-rule.ts';

const ruleTester = new RuleTester();

ruleTester.run('my-rule', rule, {
  valid: [
    /* ... */
  ],
  invalid: [
    {
      code: 'const a = 1;',
      // Remove the line with string form of `output`
      output: 'const b = 1;',
      // Add the line with array form of `output`
      output: ['const b = 1;', 'const c = 1;'],
      errors: [
        /* ... */
      ],
    },
  ],
});

See [rule-tester] support multipass fixes for more details.

Other Developer-Facing Breaking Changes​

• feat(parser): always enable comment, loc, range, tokens
  • If you were manually calling @typescript-eslint/parser functions, those options are no longer necessary to provide
• chore(type-utils)!: remove IsNullableTypeOptions interface
  • If you were using isNullableType, you can omit its section parameter
• feat(utils): swap LegacyESLint out for FlatESLint as ESLint export
  • If you still need to use the class corresponding to legacy ("eslintrc") configs, switch from importing ESLint to LegacyESLint
• chore(type-utils): remove getTypeArguments
  • If you were using getTypeArguments, call a TypeScript type checker's checker.getTypeArguments instead
• feat(utils): remove deprecated context helpers
  • You should consider dropping support for older ESLint versions and migrate to the new APIs.

Appreciation​

We'd like to extend a sincere thank you to everybody who pitched in to make typescript-eslint v8 possible.

• Ourselves on the maintenance team:
  • Auvred
  • Armano
  • Brad Zacher
  • James Henry
  • Josh Goldberg
  • Joshua Chen
  • Kirk Waiblinger
• Community contributors whose PRs were merged into the 8.0.0 release:
  • Abraham Guo
  • Arka Pratim Chaudhuri
  • Christopher Aubut
  • Collin Bachman
  • Thomas Huchedé
  • Victor Lin
  • Yukihiro Hasegawa
• Community maintainers and projects who worked with us to try out the v8 beta:
  • Babel with Nicolò Ribaudo
  • create-t3-app with Julius Marminge
  • postcss-plugins with Romain Menke
  • Prettier with fisker Cheung
  • RedwoodJS with Tobbe Lundberg
  • SvelteKit with Ben McCann
  • tRPC with Alex Katt
  • Vite with Bjorn Lu
• Community plugins and projects who worked with us to try out the v8 beta:
  • eslint-plugin-functional with Rebecca Stevens
  • eslint-plugin-import-x with Sukka
  • eslint-plugin-jest with Simen Bekkhus
  • eslint-plugin-vitest with Verité Mugabo
  • eslint-react with Eva1ent
  • eslint-angular with James Henry
  • eslint-stylistic with Anthony Fu
• Members of the TypeScript team who helped with performance issues:
  • Daniel Rosenwasser
  • Jake Bailey
  • Sheetal Nandi

See the v8.0.0 milestone for the list of issues and associated merged pull requests.

Supporting typescript-eslint​

If you enjoyed this blog post and/or use typescript-eslint, please consider supporting us on Open Collective. We're a small volunteer team and could use your support to make the ESLint experience on TypeScript great. Thanks! 💖

typescript-eslint is the tooling that enables standard JavaScript tools such as ESLint and Prettier to support TypeScript code. We've been working on a set of breaking changes and general features that we're excited to get in front of users soon. And now, we're excited to say that typescript-eslint v8 is ready for public beta testing! 🎉

Our plan for typescript-eslint v8 is to:

1. Have users try out betas starting in May of 2024
2. Respond to user feedback for the next ~1-2 months
3. Release a stable version within the next ~1-2 months

Nothing mentioned in this blog post is set in stone. If you feel passionately about any of the choices we've made here — positively or negatively — then do let us know on the typescript-eslint Discord's #v8 channel!

Trying Out v8​

Please do try out the typescript-eslint v8 beta!

As A New User​

If you don't yet use typescript-eslint, you can go through our configuration steps on the v8 Getting Started docs. It'll walk you through setting up typescript-eslint in a project.

To use v8 specifically, see the following section for an updated install command.

As An Existing User​

If you already use typescript-eslint, you'll need to first replace your package's previous versions of @typescript-eslint/eslint-plugin and @typescript-eslint/parser with @rc-v8 versions:

npm i typescript-eslint@rc-v8 --save-dev

npm i @typescript-eslint/eslint-plugin@rc-v8 @typescript-eslint/parser@rc-v8 --save-dev

We highly recommend then basing your ESLint configuration on the reworked typescript-eslint recommended configurations — especially if it's been a while since you've reworked your linter config.

User-Facing Changes​

These are the changes that users of typescript-eslint —generally, any developer running ESLint on TypeScript code— should pay attention to when upgrading typescript-eslint from v7 to v8.

ESLint v9 Support​

typescript-eslint v8 ships with full support for ESLint v9.

typescript-eslint v7 was our first version that supported ESLint's new "flat" config file format, which was already available in ESLint v8. ESLint v9 still supports ESLint's older legacy config file format so our tooling does as well. However, ESLint v9 also includes a set of breaking changes that we added support for in typescript-eslint v8. See the ESLint v9 release blog post for more details.

Project Service​

The biggest new feature added in this version is the stability of our new "project service". In short, the project service is a new way to enable typed linting that is generally easier to configure and faster at runtime than our previous offerings. It's been experimentally available since v6.1.0 under the name EXPERIMENTAL_useProjectService; now, we've renamed it to projectService.

You can use the new project service in your configuration instead of the previous parserOptions.project:

import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.recommendedTypeChecked,
  {
    languageOptions: {
      parserOptions: {
        project: true,
        projectService: true,
        tsconfigRootDir: import.meta.dirname,
      },
    },
  },
);

The project service will automatically find the closest tsconfig.json for each file (like project: true). It also allows enabling typed linting for files not explicitly included in a tsconfig.json. This should remove the need for custom tsconfig.eslint.json files to lint files like eslint.config.mjs!

Typed linting for out-of-project files can be done by specifying two properties of a parserOptions.projectService object:

• allowDefaultProject: a glob of a small number of out-of-project files to enable a slower default project on
• defaultProject: path to a TypeScript configuration file to use for the slower default project

import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.recommendedTypeChecked,
  {
    languageOptions: {
      parserOptions: {
        project: ['packages/*/tsconfig.json', 'tsconfig.eslint.json'],
        projectService: {
          allowDefaultProject: ['*.js'],
          defaultProject: 'tsconfig.json',
        },
        tsconfigRootDir: import.meta.dirname,
      },
    },
  },
);

Internally, the project service uses the same TypeScript APIs that editors such as VS Code use. Doing so should make it harder to accidentally configure different type information for ESLint than what you see in day-to-day editing.

We're thrilled to have the project service option promoted to stable in v8. We'll soon release a dedicated parserOptions blog post walking through the new option in more details. 🚀

Updated Configuration Rules​

Every new major version of typescript-eslint comes with changes to which rules are enabled in the preset configurations and with which options. Because this release also includes a reworking of the configurations themselves, the list of changes is too large to put in this blog post. Instead see the table in Changes to configurations for 8.0.0 for a full list of the changes.

Please do try out the new rule configurations presets and let us know in that discussion!

Rule Breaking Changes​

Several rules are changed in significant enough ways to be considered breaking changes:

• Rules: Deprecate prefer-ts-expect-error in favor of ban-ts-comment
  • If you have @typescript-eslint/prefer-ts-expect-error manually enabled, remove that, and instead either use a recommended config or manually enable @typescript-eslint/ban-ts-comment.
• chore(eslint-plugin): deprecate no-var-requires in favor of no-require-imports
  • If you have @typescript-eslint/no-var-requires manually enabled, remove that, and instead either use a recommended config or manually enable @typescript-eslint/no-require-imports.
• feat(eslint-plugin): remove deprecated no-throw-literal rule
  • If you have @typescript-eslint/no-throw-literal manually enabled, remove that, and instead either use a recommended config or manually enable @typescript-eslint/only-throw-error.
• feat(eslint-plugin): [no-useless-template-literals] rename to no-useless-template-expression (deprecate no-useless-template-literals) and fix: no-useless-template-expression -> no-unnecessary-template-expression
  • Find-and-replace text from no-useless-template-literals to no-unnecessary-template-expression
• feat(eslint-plugin): deprecate no-loss-of-precision extension rule
  • If you have @typescript-eslint/no-loss-of-precision manually enabled, replace it with the base rule no-loss-of-precision.
• feat(eslint-plugin): remove formatting/layout rules
  • If you're using any of the old deprecated formatting rules, see eslint.style for their new equivalents
• feat(eslint-plugin): [prefer-nullish-coalescing] change ignoreConditionalTests default to true
  • If you want to have the rule check conditional tests, set its ignoreConditionalTests option to false in your ESLint config
• feat(eslint-plugin): [no-unused-vars] align catch behavior to ESLint 9
  • If you want @typescript-eslint/no-unused-vars to ignore caught errors, enable its caughtErrors option to 'none' in your ESLint config

Replacement of ban-types​

@typescript-eslint/ban-types has long been one of the more controversial rules in typescript-eslint. It served two purposes:

• Allowing users to ban a configurable list of types from being used in type annotations
• Banning confusing or dangerous built-in types such as Function and Number

Notably, ban-types banned the built-in {} ("empty object") type in TypeScript. The {} type is a common source of confusion for TypeScript developers because it matches any non-nullable value, including primitives like "".

Banning {} in ban-types was helpful to prevent developers from accidentally using it instead of a more safe type such as object. On the other hand, there are legitimate uses for {}, and banning it by default was harmful in those cases.

typescript-eslint v8 deletes the ban-types rule and replaces it with several more targeted rules:

• @typescript-eslint/no-restricted-types is the new rule for banning a configurable list of type names. It has no options enabled by default. It has no options enabled by default.
• @typescript-eslint/no-empty-object-type bans the built-in {} type in confusing locations.
• @typescript-eslint/no-unsafe-function-type bans the built-in Function type.
• @typescript-eslint/no-wrapper-object-types bans Object and built-in class wrappers such as Number.

To migrate to the new rules:

• If you were disabling the ban on {}, consider enabling @typescript-eslint/no-empty-object-type, as it allows some cases of {} that were previously banned.
• If you were banning any configurable types lists, provide a similar configuration to no-restricted-types.
• If you have @typescript-eslint/ban-types manually enabled, it will no longer ban:
  • {} or object: use a recommended config or manually enable @typescript-eslint/no-empty-object-type.
  • Function: use a recommended config or manually enable @typescript-eslint/no-unsafe-function-type.
  • Number or other built-in uppercase types: use a recommended config or manually enable @typescript-eslint/no-wrapper-object-types.
• If you have @typescript-eslint/no-empty-interface manually enabled, remove that, and instead either use a recommended config or manually enable @typescript-eslint/no-empty-object-type.

For more details, see the issues and pull requests that split apart the ban-types rule:

• Enhancement: [ban-types] Split the ban into a separate, better-phrased rule
• feat(eslint-plugin): split no-empty-object-type out from ban-types and no-empty-interface
• Enhancement: [ban-types] Split into default-less no-restricted-types and more targeted type ban rule(s)
• feat(eslint-plugin): replace ban-types with no-restricted-types, no-unsafe-function-type, no-wrapper-object-types

Tooling Breaking Changes​

• Enhancement: Error if configuration options aren't provided as expected: postponed to a future major version
• fix(typescript-estree): enable dot globs for project by default
  • This will cause any parserOptions.project globs to match dot (.) directories. If you don't want to match them then use a more specific set of globs, or switch to parserOptions.projectService.
• feat(typescript-estree): remove slow deprecated and isolated programs
  • If you were still using parserOptions.DEPRECATED__createDefaultProgram, switch to parserOptions.projectService (recommended) or parserOptions.project.
• feat(typescript-estree): rename automaticSingleRunInference to disallowAutomaticSingleRunInference
  • We've updated the default to be an opt-out - meaning you no longer need to enable it:

    parserOptions: {
      automaticSingleRunInference: true,
      // ...
    }
    
• chore: bump minimum versions for v8
  • ESLint support range was changed from ^8.56.0 to ^8.57.0
  • Node.js support range was changed from ^18.18.0 || >=20.0.0 to ^18.18.0 || ^20.9.0 || >=21.1.0
  • TypeScript support range was changed from >=4.7.4 <5.5.0 to >=4.8.4 <5.5.0
• Parser: remove EXPERIMENTAL_useSourceOfProjectReferenceRedirect in favor of project service
  • We now recommend using the new parserOptions.projectService instead

Developer-Facing Changes​

typescript-eslint v8 comes with a suite of cleanups and improvements for developers using its Node.js APIs as well. If you author any ESLint plugins or other tools that interact with TypeScript syntax, then we recommend you try out typescript-eslint v8 soon. It includes some breaking changes that you may need to accommodate for.

AST Breaking Changes​

These changes are to the AST shapes generated by typescript-eslint when parsing code. If you author any ESLint rules that refer to the syntax mentioned by them, these are relevant to you.

• Enhancement: add strict parent types for nodes that have well-defined parents
  • This will help you remove some unnecessary conditions - we suggest using @typescript-eslint/no-unnecessary-condition to help find the unnecessary checks!
• feat(typescript-estree): split TSMappedType typeParameter into constraint and key
  • If your code handles mapped types, change from node.typeParameter.constraint to node.constraint and from node.typeParameter.name to node.key
• feat(ast-spec): remove deprecated type params
  • If you haven't already you must stop using those removed AST properties that were already marked as @deprecated
• fix(typescript-estree): add TSEnumBody node for TSEnumDeclaration body #8920
  • If your code handles enums, switch from node.members to node.body.members

Custom Rule meta.docs Types​

@typescript-eslint/utils has long exported a RuleCreator utility for making custom well-typed custom ESLint rules. That RuleCreator is used internally by @typescript-eslint/eslint-plugin — and in fact, up through typescript-eslint v7, it hardcoded the same types for rules' meta.docs as @typescript-eslint/eslint-plugin!

In typescript-eslint v8, we've made two changes to RuleCreator:

• Rule meta.docs by default only allows the properties defined in ESLint's Custom Rules > Rule Structure docs: description and url
• RuleCreator allows an optional type parameter to specify additional allowed properties

For example, this rule includes the common meta.docs.recommended property as a boolean:

interface MyPluginDocs {
  recommended: boolean;
}

const createRule = ESLintUtils.RuleCreator<MyPluginDocs>(
  name => `https://example.com/rule/${name}`,
);

createRule({
  // ...
  meta: {
    docs: {
      description: '...',
      recommended: true,
    },
    // ...
  },
});

See feat(utils): allow specifying additional rule meta.docs in RuleCreator for more details.

Flat Configuration RuleTester​

The RuleTester provided by @typescript-eslint/rule-tester is a fork of ESLint's RuleTester. In typescript-eslint v7 and earlier, RuleTester's constructor allowed providing legacy "eslintrc" options -- mirroring ESLint v8 and earlier. In typescript-eslint v8, RuleTester's constructor now instead allows providing new "flat" config options -- mirroring ESLint v9.

Per ESLint flat configs, any parser configurations you provide will need to be inside a languageOptions property:

import { RuleTester } from '@typescript-eslint/rule-tester

const ruleTester = new RuleTester({
  languageOptions: {
    parserOptions: {
      tsconfigRootDir: import.meta.dirname,
    },
  },
});

Any parser you provide will need to be the parser itself, rather than a string name of the package:

import { RuleTester } from '@typescript-eslint/rule-tester
import jsoncParser from "jsonc-eslint-parser";

const ruleTester = new RuleTester({
  languageOptions: {
    parser: jsoncParser,
    parser: "jsonc-eslint-parser",
  },
});

This change brings typescript-eslint's RuleTester in line with ESLint's RuleTester and flat config. In doing so, it changes two parserOptions defaults:

• ecmaVersion: from 5 to 'latest'
• sourceType: from 'script' to 'module'

If you were specifying either or both of those in your tests, you likely can now omit them:

import { RuleTester } from '@typescript-eslint/rule-tester

const ruleTester = new RuleTester();
const ruleTester = new RuleTester({
  parserOptions: {
    ecmaVersion: 2018,
    sourceType: 'module',
  },
});

For more details, see:

• ESLint > Migrate to 9.0.0 > FlatRuleTester is now RuleTester
• typescript-eslint > feat(rule-tester): switched to flat config

Support for multi-pass fixes in RuleTester​

One limitation of ESLint's RuleTester is that it is not possible to verify the individual applied fixes when a rule provides multiple rounds of fixes. ESLint's RuleTester applies only the first fix when there is conflict between two fixes.

In typescript-eslint v8, our RuleTester tries to apply all possible fixes for each test case.

If your rule tests had some test cases that required multi-pass fixes, you will see some test failures. To fix these failures, provide an array of strings for output which specifies the output after each fix pass.

import { RuleTester } from '@typescript-eslint/rule-tester';
import rule from '../src/rules/my-rule.ts';

const ruleTester = new RuleTester();

ruleTester.run('my-rule', rule, {
  valid: [
    /* ... */
  ],
  invalid: [
    {
      code: 'const a = 1;',
      // Remove the line with string form of `output`
      output: 'const b = 1;',
      // Add the line with array form of `output`
      output: ['const b = 1;', 'const c = 1;'],
      errors: [
        /* ... */
      ],
    },
  ],
});

See [rule-tester] support multipass fixes for more details.

Other Developer-Facing Breaking Changes​

• Repo: Rule [options] parameter should be non-nullable if defaultOptions exists: blocked on external features in ESLint and TypeScript
• feat(parser): always enable comment, loc, range, tokens
  • If you were manually calling @typescript-eslint/parser functions, those options are no longer necessary to provide
• chore(type-utils)!: remove IsNullableTypeOptions interface
  • If you were using isNullableType, you can omit its section parameter
• feat(utils): swap LegacyESLint out for FlatESLint as ESLint export
  • If you still need to use the class corresponding to legacy ("eslintrc") configs, switch from importing ESLint to LegacyESLint
• chore(type-utils): remove getTypeArguments
  • If you were using getTypeArguments, call a TypeScript type checker's checker.getTypeArguments instead
• feat(utils): remove deprecated context helpers
  • You should consider dropping support for older ESLint versions and migrate to the new APIs.

Appreciation​

We'd like to extend a sincere thank you to everybody who pitched in to make typescript-eslint v8 possible.

• Ourselves on the maintenance team:
  • Auvred
  • Armano
  • Brad Zacher
  • James Henry
  • Josh Goldberg
  • Joshua Chen
  • Kirk Waiblinger
• Community contributors whose PRs were merged into the 8.0.0 release:
  • Abraham Guo
  • Arka Pratim Chaudhuri
  • Christopher Aubut
  • Collin Bachman
  • Thomas Huchedé
  • Victor Lin
  • Yukihiro Hasegawa
• Members of the TypeScript team who helped with performance issues:
  • Daniel Rosenwasser
  • Jake Bailey
  • Sheetal Nandi

See the v8.0.0 milestone for the list of issues and associated merged pull requests.

Supporting typescript-eslint​

If you enjoyed this blog post and/or use typescript-eslint, please consider supporting us on Open Collective. We're a small volunteer team and could use your support to make the ESLint experience on TypeScript great. Thanks! 💖

Experimental Decorator Metadata​

TypeScript's experimentalDecorators compiler option (referred to as "legacy decorators" from here on) turns on support for an old version of the JavaScript TC39 decorator proposal that was never standardized. TypeScript's legacy decorators are similar to the current proposal, but differ in that they use metadata reflection when TypeScript's emitDecoratorMetadata compiler option is turned on.

When using legacy decorators with decorator metadata and a class is annotated with decorators, TypeScript will emit runtime metadata for the class (see the example below). That decorator metadata will capture property types, method parameter types, and method return types. Decorator metadata provides a bridge between the types (which are not available at compile time) and the runtime code.

The downside of generating this runtime code that it is derived using type information: meaning that the runtime code emitted changes based on the cross-file type information that TypeScript has computed. Doing so violates a key TypeScript design goal of not changing runtime behavior based on type information.

To illustrate what this means consider the following snippet:

import Foo from 'foo';
import decorator from 'decorator';

class Clazz {
  @decorator
  method(arg: Foo) {}
}

TypeScript will transpile this code to the following:

import { __decorate, __metadata } from "tslib";
import Foo from 'foo';
import decorator from 'decorator';
class Clazz {
    method(arg) { }
}
__decorate([
    decorator,
    __metadata("design:type", Function),
    __metadata("design:paramtypes", /* See below for what this value will be */),
    __metadata("design:returntype", void 0)
], Clazz.prototype, "method", null);

If the imported name Foo resolves to...

• a type then TS will emit [Function], [Object], [String], [Number], or [Boolean] depending on what that type resolves to.
• an enum then TS will emit one of [String], [Number], or [Object] depending on the type of the enum's members
  • [Object] is used for an enum that has both string and number values.
• a class declaration:
  • and the import is NOT annotated as import type then TS will emit [Foo].
  • and the import IS annotated as import type then TS will emit [Function].

In addition to requiring runtime type information, those metadata emit rules are confusing for developers to reason about. They necessitate understanding edge cases specific to TypeScript's handling of decorators and type information.

consistent-type-imports caused runtime breakage​

The important piece is that last dot point above - the handling of imported names that resolve to class declarations. If the import is not annotated as import type then TS emits a runtime reference to the imported name. This runtime reference is implicit and requires type information to derive - you cannot derive its existence purely based on single-file AST analysis.

The consistent-type-imports rule was introduced to allow users to enforce that any imported names are annotated as import type if they are not used in a value location. How the rule makes this decision is based solely on the single file it's looking at. But another way the rule does not use any type information from TS and instead it scans the code using a technique called "scope analysis" so that it can find all references to the imported names and determine if each reference is a value reference.

The issue arises with legacy decorators and decorator metadata - syntactically the only reference to Foo is a type reference. However the emitted code contains a hidden reference to Foo. When the rule relies upon the code it sees then it will report an error and attempt to mark Foo as import type. If the user applies this fix then that will cause their runtime code to change (arg's metadata goes from Foo to Function) which can have downstream runtime impacts and cause broken code!

Past (Broken) Solution​

In the past we tried to solve this problem by enforcing that imported names that are used in decorator metadata are specifically not marked as type-only imports to ensure that values are always correctly emitted in the runtime code.

However this solution had a hidden pitfall; if the user also used isolatedModules: true then TS will enforce that all imported types are explicitly marked as import type for compatibility with single-file build tools. This lead to an unresolvable situation where consistent-type-imports would enforce that an imported name must not be marked with import type so that we could ensure we don't break decorator metadata, and simultaneously TS would enforce that that same imported name must be marked with import type.

There have been a few attempts to fix this issue but the resolution we came to was that the only solution was to add type information to the rule so that it could correctly understand all of the above type-aware constraints. Adding type information to an existing rule is something we try to avoid because it is a major breaking change that restricts the rule to just users that leverage type-aware linting.

Adding type-information to the rule to handle this edge case would not be a positive change for users or the ecosystem:

1. Many users are unable to configure typed linting and/or unwilling to take its performance hit. Requiring type-aware linting linting for this rule to serve a very small subset of impacted users would reduce the linting ability of many more un-impacted users.
2. It requires a specific combinations of compiler options to trigger it means that not everyone is impacted by the problem - so we'd be preventing a lot of un-impacted users from using the rule.
3. With the release of TypeScript v5.0 and its stable decorators experimentalDecorators are now the legacy syntax. Whilst TypeScript v5.2 added support for the latest stable decorator metadata proposal this proposal does not include type metadata - so it doesn't suffer the same drawbacks as its legacy counterpart.

Today's Solution - the Compromise​

Ultimately we determined the best solution was to just opt-out of handling this use-case entirely. This means that we can avoid accidentally reporting the wrong thing and fixing to code that either fails to compile or alters the emitted runtime metadata.

Now, if you have both experimentalDecorators: true and emitDecoratorMetadata: true, then the consistent-type-imports rule will not report any errors within any files that contain decorators.

All files without decorators will continue to report as expected. Similarly all projects that use experimentalDecorators: false and/or emitDecoratorMetadata: false will continue to report as expected.

Configuring the linter to expect experimentalDecorators: true and emitDecoratorMetadata: true​

If you are using type-aware linting then we will automatically infer your setup from your tsconfig and you should not need to configure anything manually.

Otherwise you can explicitly tell our tooling to analyze your code as if the compiler option was turned on by setting both parserOptions.emitDecoratorMetadata = true and parserOptions.experimentalDecorators = true. For example:

import tseslint from 'typescript-eslint';

export default tseslint.config(
  ...tseslint.configs.recommended,
  {
    languageOptions: {
      parserOptions: {
        emitDecoratorMetadata: true,
        experimentalDecorators: true,
      },
    },
  },
);

Alternatives for Impacted Users​

If you are working in a workspace that is impacted by this change and want to correctly have your imports consistently marked with type, we suggest using the verbatimModuleSyntax compiler option which will use type information to correctly enforce that types are marked with type and values are not when they are used in decorator metadata.

Supporting typescript-eslint​

If you enjoyed this blog post and/or use typescript-eslint, please consider supporting us on Open Collective. We're a small volunteer team and could use your support to make the ESLint experience on TypeScript great. Thanks! 💖

We've been working on infrastructure improvements that will help ensuring long-term interoperability with other tools in the ecosystem. In particular this major release tightens our dependency requirements to help set us up for ESLint v9 and includes a new package typescript-eslint providing full support for flat config files!

Breaking Changes​

This is a small major release with just three breaking changes:

1. Update Node.js engine requirement to ^18.18.0 || >=20.0.0. This means we are dropping support for Node 16, 19, and Node 18 versions prior to 18.18.0. Note that this is the same requirement that ESLint v9 will impose.
2. Update the TypeScript peer dependency requirement to >=4.7.4.
3. Update the ESLint peer dependency requirement to ^8.56.0.

For most users this means that an upgrade from v6 should just look like this:

npm i eslint typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin

yarn add eslint typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin

pnpm add eslint typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin

Into the Future​

The intent behind this release is for us to constrain variance in our dependencies to help set us up for the future. The upcoming ESLint v9 release will contain many API removals - all of which had replacements added in some of the latest ESLint v8 releases. By enforcing that you have the latest ESLint v8 release we ensure that you have the replacement APIs. This significantly reduces our maintenance burden and should mean we can release v9 support sooner and with less pain and effort.

New Features - Flat Config Support​

There is one big feature that's also shipping with this release:
🎉 Official support for ESLint Flat Configs! 🎉

With v7 we're releasing a new package, typescript-eslint. This package can be imported within your flat config to access our configs, plugin, and parser. This package also exports a utility function called config which will allow you to write type-checked configuration files!

Switching to typescript-eslint​

Because this new package includes dependencies on our plugin and parser, you can replace those dependencies entirely:

npm un @typescript-eslint/parser @typescript-eslint/eslint-plugin
npm i typescript-eslint

yarn remove @typescript-eslint/parser @typescript-eslint/eslint-plugin
yarn add typescript-eslint

pnpm remove @typescript-eslint/parser @typescript-eslint/eslint-plugin
pnpm add typescript-eslint

The simplest of this new tooling would be the following which will enable the ESLint recommended config and our recommended config (including turning on our plugin and parser):

// @ts-check

import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.recommended,
);

If you're into having a bit more control then you can also declare our plugin and parser in your config - both are exported from this package! For example this config would enable our plugin, our parser, and type-aware linting with a few of our popular type-aware rules:

// @ts-check

import tseslint from 'typescript-eslint';

export default tseslint.config({
  plugins: {
    '@typescript-eslint': tseslint.plugin,
  },
  languageOptions: {
    parser: tseslint.parser,
    parserOptions: {
      project: true,
    },
  },
  rules: {
    '@typescript-eslint/no-unsafe-argument': 'error',
    '@typescript-eslint/no-unsafe-assignment': 'error',
    '@typescript-eslint/no-unsafe-call': 'error',
    '@typescript-eslint/no-unsafe-member-access': 'error',
    '@typescript-eslint/no-unsafe-return': 'error',
  },
});