Type-Aware Linting Alpha

CameronCore
CamMember

We're excited to announce the alpha release of type-aware linting in Oxlint!

Overview

Following our technical preview in August, we're excited to announce that type-aware linting has reached alpha status. This milestone brings significant improvements in stability, configurability, and rule coverage.

Type-aware linting enables powerful rules like no-floating-promises, no-misused-promises, and await-thenable that catch bugs by utilizing TypeScript's type system. With 43 type-aware rules now available, you can catch entire categories of runtime errors before they happen.

In this post:

Quick Start - Get started with type-aware linting in minutes
Performance - See how much faster type-aware linting is compared to ESLint
What's new since the technical preview - New features and improvements
Technical details - How type-aware linting works under the hood
What's next - Upcoming improvements for the beta release

Quick Start

Install oxlint and oxlint-tsgolint, then run with the --type-aware flag:

npmpnpmyarnbun

npm add -D oxlint oxlint-tsgolint@latest
npx oxlint --type-aware

pnpm add -D oxlint oxlint-tsgolint@latest
pnpm oxlint --type-aware

yarn add -D oxlint oxlint-tsgolint@latest
yarn oxlint --type-aware

bun add -D oxlint oxlint-tsgolint@latest
bunx oxlint --type-aware

To try a specific type-aware rule without other configuration (oxlint-tsgolint must be installed globally or locally already):

npmpnpmyarnbun

npx oxlint --type-aware -A all -D typescript/no-floating-promises

pnpx oxlint --type-aware -A all -D typescript/no-floating-promises

yarn oxlint --type-aware -A all -D typescript/no-floating-promises

bunx oxlint --type-aware -A all -D typescript/no-floating-promises

For more configuration options, see our usage guide.

Performance

Project	Oxlint + Type Aware	ESLint + typescript-eslint	Improvement
vuejs/core	2.531 s	20.800 s	8.22x
outline/outline	4.448 s	55.070 s	12.38x

Benchmarks were performed on a MacBook Pro M2 Max 12 Cores (8 performance and 4 efficiency).

Our performance testing shows that oxlint with type-aware linting is around 10 times faster than eslint with typescript-eslint. Take a look at our performance benchmarks for more details.

Oxlint can also be used to typecheck your codebase while linting. This avoids a duplicate work, as much of the type information is already computed during type-aware linting.

Known Issues

While tsgolint is ready for testing in production codebases, you may encounter issues with running out of memory when working with very large codebases. We are working on optimizing the memory usage for the next milestone. We would love if you tried tsgolint and reported any out-of-memory issues to us in the tsgolint repository and included some details about your project to help us improve memory usage.

What's new since the technical preview?

Support for type-checking while linting

tsgolint now supports emitting type checking errors from TypeScript while linting. Since type-aware rules already require checking all of the types within a file, we are able to use this existing type information rather than discarding it. This means that in some cases, it is possible to skip doing a separate type-check command altogether (e.g., tsc --noEmit), reducing total time spent doing linting and type-checking in CI.

This is an experimental feature, but you can enable it by adding the --type-check and --type-aware flag to the oxlint command:

$ oxlint --type-aware --type-check

  × typescript(TS2322): Type 'number' is not assignable to type 'string'.
   ╭─[index.ts:1:7]
 1 │ const message: string = 1
   ·       ───────
   ╰────

Rule configuration support in `oxlint`

Type-aware rules that run in tsgolint can be configured in oxlint just like any other lint rule. For example, you can configure the no-floating-promises rule to allow certain safe calls or ignore void:

json

{
  "rules": {
    "typescript/no-floating-promises": [
      "error",
      {
        "ignoreVoid": true,
        "allowForKnownSafePromises": [
          { "from": "file", "name": "SafePromise" },
          { "from": "lib", "name": "PromiseLike" }
        ]
      }
    ]
  }
}

The configuration options are aligned with what typescript-eslint supports and documentation can be found in the configuration section for each rule (like no-floating-promises).

Inline disable comment support in `oxlint`

Rules that run in tsgolint can now be disabled similar to any other oxlint rule by placing a comment in the file or on a line:

/* oxlint-disable typescript/no-floating-promises */

// oxlint-disable-next-line typescript/no-floating-promises
[1, 2, 3].map(async (x) => x + 1);

More supported rules

We've continued to make progress on porting popular rules from typescript-eslint which you can now use via oxlint. tsgolint, combined with oxlint, currently supports 43 type-aware rules.

Since the initial preview, support for the following rules has also been added:

no-deprecated (one of the most commonly requested rules)
prefer-includes
strict-boolean-expressions

TypeScript program diagnostics are now reported

Previously, if TypeScript failed to create and parse a program, these errors were not reported which led to confusion around why linting was not working. Now, we report any issues with creating a program as a diagnostic, including configuration issues in tsconfig.json files.

For example, if a tsconfig.json file contains baseUrl, that will be reported as an error, since baseUrl has been removed from TypeScript in v7.0:

$ oxlint --type-aware

  × typescript(tsconfig-error): Invalid tsconfig
   ╭─[tsconfig.json:4:3]
 3 │     "compilerOptions": {
 4 │         "baseUrl": ".",
   ·         ─────────
 5 │         "experimentalDecorators": true,
   ╰────
  help: Option 'baseUrl' has been removed. Please remove it from your configuration.
        See https://github.com/oxc-project/tsgolint/issues/351 for more information.

Automatic fixes for type-aware rules

Type-aware rules now support automatic fixes via the --fix flag. When you run oxlint --type-aware --fix, fixable diagnostics from tsgolint are applied just like regular oxlint fixes. This brings full parity with non-type-aware rules for the fix workflow.

Technical details

Architecture

Type-aware linting in Oxlint uses a unique two-binary architecture:

oxlint CLI (Rust)
  ├─ Handles file traversal, ignore logic, and diagnostics
  ├─ Runs non-type-aware rules and custom JS plugins
  ├─ Passes paths and configuration to tsgolint
  └─ Formats and displays results

tsgolint (Go)
  ├─ Uses typescript-go directly for type checking
  ├─ Executes type-aware rules
  └─ Returns structured diagnostics

This design keeps Oxlint's core fast while leveraging TypeScript's type system through typescript-go. The frontend-backend separation means oxlint controls the user experience while tsgolint handles the heavy lifting of type analysis.

TypeScript compatibility

tsgolint is based on typescript-go, Microsoft's Go-based rewrite that will become TypeScript v7.0. For more details on TypeScript 7's progress, see the official TypeScript blog post. This means that you might encounter some features which are no longer supported.

Important compatibility notes:

Only TypeScript 7.0+ features are supported
Pre-7.0 syntax and deprecated features are not supported
Legacy tsconfig.json options like baseUrl have been removed in TypeScript 7.0

If you're using deprecated features from TypeScript 6.0 or earlier, you'll need to migrate your codebase first. See the TypeScript migration guide for help updating deprecated tsconfig options.

Implementation details

tsgolint doesn't use typescript-go's public APIs. Instead, it compiles typescript-go by shimming internal APIs to make them accessible. We actively track typescript-go updates and fix breaking changes as needed.

Our typescript-go fork is synced regularly using renovatebot, ensuring we stay current with the latest improvements and fixes. Once TypeScript 7.0 is officially released, we will track stable releases rather than the tip of the main branch.

What's next

We're actively working on the following improvements for the beta release:

More supported rules - Currently we support 43 out of the 59 type-aware rules from typescript-eslint. As we head towards a beta release, we plan to continue expanding rule coverage.
Performance and memory usage improvements - We're going to continue to optimize performance, especially for very large monorepos.

Acknowledgements

We'd like to extend our gratitude to:

The TypeScript team for creating typescript-go.
The typescript-eslint team for their heartwarming support.
@auvred for creating tsgolint.
@camchenry for continued performance work, as well as implementing rule option support.

Try it out

Ready to get started? Head to the Quick Start section above to install and run type-aware linting.

We'd love to hear your feedback on type-aware linting and are excited to see how it helps improve your development workflow.

Connect with us:

Discord: Join our community server for real-time discussions
GitHub: Share feedback on GitHub Discussions
Issues: Report oxlint bugs to oxc and type-aware linting bugs to tsgolint.

Overview ​

Quick Start ​

Performance ​

What's new since the technical preview? ​

Support for type-checking while linting ​

Rule configuration support in oxlint ​

Inline disable comment support in oxlint ​

More supported rules ​

TypeScript program diagnostics are now reported ​

Automatic fixes for type-aware rules ​

Technical details ​

Architecture ​

TypeScript compatibility ​

Implementation details ​

What's next ​

Acknowledgements ​

Try it out ​