Oxlint Type-Aware Linter Backend

0.21.1 · active · verified Sun Apr 19

Oxlint-tsgolint is a high-performance, type-aware TypeScript linter that serves as a backend for Oxlint. It leverages `typescript-go` (the Go port of TypeScript 7) to provide full compatibility with the TypeScript type system, enabling deep semantic analysis for TypeScript projects. Currently at version 0.21.1, the package maintains an active release cadence with frequent updates for bug fixes, performance improvements, and new features. Its key differentiators include performance often 20-40x faster than traditional ESLint with `typescript-eslint` on large codebases, multi-core rule execution, and broad coverage of 59 out of 61 targeted `typescript-eslint` type-aware rules. It focuses on catching production-grade bugs that syntax-only linters miss, such as unhandled promise rejections. Users integrate it by installing it alongside Oxlint and enabling type-aware checks via Oxlint's CLI and configuration files, making it a critical component for projects requiring advanced static analysis without sacrificing linting speed.

Common errors

```
Error: oxlint: Unknown flag --type-aware
```
cause The `oxlint` package was installed without `oxlint-tsgolint` or an outdated version of `oxlint` is being used that doesn't recognize the type-aware flags.

fix Install or update both packages: `pnpm add -D oxlint-tsgolint@latest oxlint@latest` (or `npm`/`yarn`). Ensure your `oxlint` version is recent enough to support type-aware features.
```
Error: Rule 'typescript/some-rule' is not enabled or does not exist.
```
cause The specific `typescript/*` rule is not configured in `.oxlintrc.json`, or the `--type-aware` flag was not passed to the `oxlint` CLI, preventing `tsgolint` from executing type-aware rules.

fix Ensure `typeAware: true` is set in your `.oxlintrc.json` options, and the rule is listed under `rules` with an appropriate severity. Alternatively, run `oxlint --type-aware --rules typescript/some-rule:error` for ad-hoc checks.
```
Error: No valid tsconfig.json found.
```
cause Type-aware linting and type-checking require a `tsconfig.json` file in the project's root directory or specified via configuration to build the TypeScript program.

fix Create a `tsconfig.json` file in your project's root. If it's located elsewhere, specify its path in your `.oxlintrc.json` or via `oxlint` CLI options.

Warnings

gotcha Oxlint-tsgolint is not a standalone linter or a directly importable JavaScript/TypeScript library. It must be used in conjunction with `oxlint` as its type-aware backend, enabled via `oxlint` CLI flags or configuration.
Fix: Ensure `oxlint` is installed and use `oxlint --type-aware` or configure `typeAware: true` in `.oxlintrc.json`. Do not attempt to import `oxlint-tsgolint` directly into your code.
gotcha While providing extensive coverage, `tsgolint` currently implements 59 out of 61 targeted `typescript-eslint` type-aware rules. Users migrating from `typescript-eslint` should review the available rules to ensure full parity for their specific needs.
Fix: Consult the `oxlint` documentation for the list of supported `typescript/*` rules. Adjust your configuration or expectations accordingly for any unsupported rules.
breaking Oxlint-tsgolint targets TypeScript 7 (codenamed Project Corsa) and is based on `typescript-go`. This implies that some deprecated features from TypeScript 6.0 or earlier, and legacy `tsconfig.json` options (e.g., `baseUrl`), may not be supported.
Fix: Update your TypeScript version to 7.0+ and migrate your codebase to remove deprecated syntax or `tsconfig.json` options. Refer to TypeScript migration guides for assistance.
gotcha Enabling type-aware linting (`--type-aware`) and type-checking (`--type-check`) through `oxlint-tsgolint` will incur performance overhead compared to syntax-only linting. While significantly faster than alternatives, it still involves deeper analysis.
Fix: Optimize your `tsconfig.json` for smaller project graphs, consider running type-aware linting only in CI, or selectively enable rules that provide the most value for your project.
gotcha Some very large monorepos or projects with extensive cross-references might experience higher memory usage or potential deadlocks with `tsgolint`, as it's an area of ongoing performance improvement.
Fix: Monitor memory usage and consider breaking down very large projects into smaller `tsconfig` contexts if issues arise. Report performance regressions to the `oxc-project/tsgolint` GitHub repository.

Install

npm install oxlint-tsgolint npm
yarn add oxlint-tsgolint yarn
pnpm add oxlint-tsgolint pnpm

Imports

Configuration
wrong:
```
import { SomeRule } from 'oxlint-tsgolint'
```
correct:
```
This package is a linter backend and is not imported directly into JavaScript/TypeScript code.
```
Developers interact with `oxlint-tsgolint` by installing it as a development dependency alongside `oxlint` and enabling its functionality via `oxlint` CLI flags (`--type-aware`, `--type-check`) or within the `.oxlintrc.json` configuration file.

Quickstart

Demonstrates how to install `oxlint-tsgolint` via `oxlint` and run a basic type-aware linting scan, including an example of `.oxlintrc.json` configuration for specific rules.

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

// Run a basic type-aware linting scan on your project
pnpm dlx oxlint --type-aware

// Optionally, run with type-checking diagnostics
pnpm dlx oxlint --type-aware --type-check

// Configure rules in .oxlintrc.json
// {
//   "options": {
//     "typeAware": true,
//     "typeCheck": true
//   },
//   "rules": {
//     "typescript/no-floating-promises": "error",
//     "typescript/no-misused-promises": "error"
//   }
// }

view raw JSON →