tsgolint: Type-Aware Linting Inside Oxlint

Why tsgolint Adds Checks That Oxlint Cannot Derive from Syntax

tsgolint addresses a specific gap in ordinary linting: some defects depend on what a value means after TypeScript has resolved types, not merely on how the source is written. Oxlint performs syntax and structural analysis. tsgolint executes the subset of rules that require TypeScript semantic analysis.

The README uses an unhandled Promise as its central example. Calling an async function can create a Promise without attaching a rejection handler or awaiting its result:

function onSubmit(user) {
  saveUser(user);
  showToast('Saved!');
}

The `typescript/no-floating-promises` rule can flag the first call. That diagnostic requires knowledge that `saveUser` returns a Promise. A syntax parser can see the function call, but it cannot establish the returned type. This is the class of problem tsgolint is designed to report, including misused Promises through `typescript/no-misused-promises`.

The intended users are teams running JavaScript or TypeScript projects through Oxlint, especially those that want semantic checks in CI without replacing Oxlint's main lint path. It is also relevant to monorepos because the documentation states that rule execution supports multicore processing. That architecture does not remove the need for a valid TypeScript project context, and the README does not document special behavior for every editor, module resolver, or mixed-language repository.

How Oxlint Delegates Type-Aware Rule Execution

The division of responsibility is explicit. Oxlint handles file discovery, configuration, and output formatting. tsgolint performs the semantic rules and emits diagnostics. Oxlint therefore remains the user-facing command, while `oxlint-tsgolint` supplies the type-aware backend for a run started with `--type-aware`.

At the analysis layer, tsgolint runs directly on `typescript-go`, the Go implementation targeted at TypeScript 7 and described by the README as compatible with the TypeScript type system. The repository layout supports this design. It is a Go module with `cmd/`, `internal/`, `tools/`, `shim/`, and a `typescript-go` submodule. The `go.mod` replaces several `github.com/microsoft/typescript-go/shim` modules with local shim directories. Those entries show that tsgolint consumes TypeScript compiler components rather than converting TypeScript's traditional JavaScript compiler stack into an ESLint execution model.

The `--type-aware` flag enables the `typescript/*` rules that require semantic analysis. The separate `--type-check` flag adds TypeScript diagnostics from `typescript-go`. That separation matters operationally: enabling tsgolint does not automatically imply that every compiler diagnostic should appear in the lint output. A team can first adopt semantic lint rules and decide separately whether its Oxlint invocation should also perform typechecking.

The architecture also creates a hard version relationship. The README says tsgolint is built directly on TypeScript 7, and its version tracks the TypeScript release it supports. In the documented `v7.0.2001` scheme, `7.0.2` represents TypeScript 7.0.2 and `001` is the tsgolint patch suffix. A TypeScript upgrade can therefore coincide with a tsgolint version change even when the project code has not changed.

Installing oxlint-tsgolint and Enabling the First Semantic Rule

The documented installation path is through Oxlint, not through a standalone global package. Install the development dependency in the project:

pnpm add -D oxlint-tsgolint@latest

The package name is `oxlint-tsgolint`, even though the backend repository is `tsgolint`. This instruction adds the Oxlint integration package to the local project, where its version can be recorded with the rest of the development dependencies.

A first run can be launched with `pnpm dlx`:

pnpm dlx oxlint --type-aware

After the integration is installed as a project dependency, the README also gives this command for a project run:

oxlint --type-aware

The flag tells Oxlint to enable `typescript/*` rules backed by semantic analysis. Configuration is more durable than relying only on the command-line flag. The README places type-aware settings and rules in `.oxlintrc.json`:

{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "options": {
    "typeAware": true,
    "typeCheck": true
  },
  "rules": {
    "typescript/no-floating-promises": "error",
    "typescript/no-misused-promises": "error"
  }
}

The `options` block activates type-aware linting and type diagnostics. The two rules establish errors for dropped Promises and invalid Promise use. The repository's `package.json` declares `[email protected]` as its package manager, while the user-facing README uses `pnpm` commands. The build-oriented `justfile` is for repository development and is not the normal installation route for an application team.

Rule Coverage, Version Coupling, and the Fork Boundary

Type-aware linting is useful only when the required rules are present. The README is internally inconsistent about coverage. Its highlights say 59 of 61 targeted `typescript-eslint` rules are implemented, while the current status says 60 of 62. The visible rule list also shows unchecked entries such as `naming-convention` and `prefer-destructuring`. An adopting team should therefore inspect the actual rule inventory for its pinned release rather than relying on the summary percentage.

The project is not attempting an unbounded collection of custom rules. The README states that external pull requests for new rules beyond those supported by `typescript-eslint` are not currently accepted. That boundary is sensible for compatibility, but it also means teams needing a project-specific semantic rule cannot treat the repository as an open-ended rule extension point.

There is a separate constraint around TypeScript releases. Since tsgolint is built directly on TypeScript 7, its version changes when the supported TypeScript version changes. A team cannot assume that every `oxlint-tsgolint` update is a routine patch. Version policy can affect CI cache use, lockfile changes, and the timing of adoption after a TypeScript 7 update. The README does not describe compatibility with earlier TypeScript major versions, so choosing it solely for the current `latest` tag requires checking the package and toolchain relationship first.

For contributors, the repository is more demanding than its install command suggests. The `justfile` initializes the `typescript-go` submodule, applies patches from `patches/*.patch`, copies TypeScript collection files, installs pnpm dependencies, and installs end-to-end dependencies separately. The Go build target produces `tsgolint` from `./cmd/tsgolint`. These are repository-maintenance details, not steps required by projects consuming Oxlint's package.

Reported Performance Claims and Their Adoption Limits

The README reports that tsgolint is 10 to 20 times faster than ESLint with typescript-eslint in the repository's benchmarks. Its table lists Apple M4 Pro results for four repositories: `microsoft/vscode` at 83.2 seconds versus 6.96 seconds, `microsoft/typescript` at 27.2 seconds versus 1.94 seconds, `typeorm/typeorm` at 13.2 seconds versus 0.75 seconds, and `vuejs/core` at 12.3 seconds versus 0.95 seconds. These are documented benchmark figures, not results from an independent review.

The architectural explanation is consistent with those numbers being plausible as a design goal: tsgolint avoids running a type-analysis engine inside a JavaScript linter, while the README identifies compiler initialization, AST conversion, parallelism, and memory use as bottlenecks in that arrangement. It also describes multicore rule execution as a tsgolint feature.

Those figures should not be transferred directly to every project. The published comparison uses specific repositories on a specific processor, while type-aware cost still depends on project size, module resolution, compiler diagnostics, enabled rules, and cache behavior. The README does not publish memory figures, startup costs for small projects, monorepo results, or a method for reproducing every table entry outside its linked `benchmarks/` directory.

The clearest comparison is therefore architectural rather than universal. ESLint with typescript-eslint embeds the type-analysis path in the JavaScript linting environment. tsgolint splits the work: Oxlint owns the lint experience and tsgolint operates on `typescript-go`. Teams already committed to ESLint's rule configuration and plugins should account for that migration surface, even if the documented performance advantage is favorable on the listed workloads.

Maintenance Signals, Licensing, and Upgrade Work

The repository is not archived, and its last push was on 2026-10-16. Recent releases include `v7.0.2004` on 2026-10-10, `v7.0.2003` on 2026-09-24, and `v7.0.2002` on 2026-09-18. These are direct maintenance signals, but they do not remove the cost of checking TypeScript version coupling and rule availability during upgrades.

The project uses the MIT license. The repository also contains `LICENSE` and `THIRD-PARTY-LICENSE` files, reflecting that the project incorporates additional components. A distribution or compliance review should examine those files rather than assuming that the top-level MIT designation alone describes every bundled dependency. This is a source-distribution observation, not legal advice.

Current development is described as focused on additional `typescript-eslint` rule support, editor integration, configuration and rule customization, and performance improvements for large monorepos. Since new rules beyond `typescript-eslint` are outside the current contribution scope, local rule development is not presented as an ordinary extension path. Consumer teams should expect to track the backend package, Oxlint integration, and the supported TypeScript version as connected dependencies.

The stable announcement cited by the README states that type-aware linting is stable. Stability here does not mean full parity with every syntax-only rule or every future `typescript-eslint` release. It indicates that the project considers its Oxlint integration stable while continuing to expand coverage and integrations.

Editorial conclusion

TypeScript projects that want semantic linting within Oxlint should evaluate tsgolint against their rule requirements and acceptance of TypeScript 7. Syntax-only projects, or codebases needing rules outside the implemented typescript-eslint set, should keep separate tooling. Before adoption, verify that oxlint-tsgolint works with the project's package manager, that .oxlintrc.json enables the required rules, and that the current rule inventory covers the diagnostics CI must enforce.

Frequently asked questions

Official sources

1. License: MIT
2. oxc-project/tsgolint on GitHub
3. Project website
4. README
5. Releases