Type-Aware Linting

Type-aware linting enables rules that rely on TypeScript’s type system, such as detecting unhandled promises or unsafe assignments. In Oxlint, type-aware linting is provided by tsgolint and integrated into the Oxlint CLI and configuration system.

This feature is currently alpha. Rule coverage, performance, and compatibility continue to improve.

Overview

Oxlint separates responsibilities between two components:

• Oxlint (Rust) Handles file traversal, ignore logic, configuration, non-type-aware rules, and reporting.

• tsgolint (Go) Builds TypeScript programs using typescript-go and executes type-aware rules, returning structured diagnostics to Oxlint.

Installation

Type-aware linting requires an additional dependency:

npm

npm add -D oxlint-tsgolint@latest

pnpm

pnpm add -D oxlint-tsgolint@latest

yarn

yarn add -D oxlint-tsgolint@latest

bun

bun add -D oxlint-tsgolint@latest

Running type-aware linting

Enable type-aware linting with the --type-aware flag:

oxlint --type-aware

When enabled, Oxlint runs standard rules and type-aware rules in the typescript/* namespace.

Type-aware linting is opt-in and does not run unless the flag is provided.

Monorepos and build outputs

Type-aware linting requires resolved type information.

In monorepos:

• Build dependent packages so .d.ts files are available
• Ensure dependencies are installed before running

pnpm install
pnpm -r build
oxlint --type-aware

Type checking diagnostics

Enable type checking to report TypeScript errors alongside lint results:

oxlint --type-aware --type-check

This mode can replace a separate tsc --noEmit step in CI:

# before
tsc --noEmit
oxlint

# after
oxlint --type-aware --type-check

Configuring type-aware rules

Type-aware rules are configured like other Oxlint rules.

{
  "plugins": ["typescript"],
  "rules": {
    "typescript/no-floating-promises": "error",
    "typescript/no-unsafe-assignment": "warn"
  }
}

Rules support the same options as their typescript-eslint equivalents.

{
  "plugins": ["typescript"],
  "rules": {
    "typescript/no-floating-promises": ["error", { "ignoreVoid": true }]
  }
}

Disable comments

Type-aware rules support inline disable comments:

// oxlint-disable-next-line typescript/no-floating-promises
doSomethingAsync();

Report unused disable comments with:

oxlint --type-aware --report-unused-disable-directives

TypeScript compatibility

Type-aware linting is powered by typescript-go.

• TypeScript 7.0+ is required
• Some legacy tsconfig options are not supported
• Invalid options are reported when --type-check is enabled

Stability notes

Type-aware linting is alpha:

• Rule coverage is incomplete
• Very large codebases may encounter high memory usage
• Performance continues to improve

Performance and debugging

If type-aware linting is slow or uses excessive memory:

1. Update both tools:

• oxlint
• oxlint-tsgolint

2. Enable debug logging:

OXC_LOG=debug oxlint --type-aware

Example output (showing key timing milestones):

2025/01/01 12:00:00.000000 Starting tsgolint
2025/01/01 12:00:00.001000 Starting to assign files to programs. Total files: 259
2025/01/01 12:00:01.000000 Done assigning files to programs. Total programs: 8. Unmatched files: 75
2025/01/01 12:00:01.001000 Starting linter with 12 workers
2025/01/01 12:00:01.001000 Workload distribution: 8 programs
2025/01/01 12:00:01.002000 [1/8] Running linter on program: /path/to/project/jsconfig.json
...
2025/01/01 12:00:01.100000 [4/8] Running linter on program: /path/to/project/tsconfig.json
2025/01/01 12:00:02.500000 Program created with 26140 source files
2025/01/01 12:00:14.000000 /path/to/project/oxlint-plugin.mts
...
2025/01/01 12:00:14.100000 [5/8] Running linter on program: /path/to/project/apps/tsconfig.json
...
2025/01/01 12:00:15.000000 Linting Complete
Finished in 16.4s on 259 files with 161 rules using 12 threads.

How to interpret the log:

• File assignment phase (Starting to assign files... → Done assigning files...): Maps source files to their tsconfig projects. This phase should be fast. If slow, please file an issue.
• Program linting ([N/M] Running linter on program...): Each TypeScript project is linted separately. Programs that take significantly longer may indicate expensive type resolution or an overly large project.
  • Look for programs with an unusually high number of source files (e.g., Program created with 26140 source files). This may indicate misconfigured tsconfig includes/excludes pulling in unnecessary files like node_modules.
  • Each file path logged indicates when that file is being linted. Large time gaps between files may indicate expensive type resolution for certain files.

Next steps

• Check implemented rules
• Report issues to https://github.com/oxc-project/tsgolint