--- title: "Type-Aware Linting | Oxlint | The JavaScript Oxidation Compiler" section: "raw" type: "source" created: "2026-08-27" updated: "2026-08-27" canonical: "https://pyweb.dev/wiki/raw/articles/oxlint-type-aware-linting-2026" --- # Type-Aware Linting | Oxlint | The JavaScript Oxidation Compiler [![](https://oxc.rs/assets/footer-background.DMNuC46B.jpg)\\ \\ ![Oxc icon](data:image/svg+xml,%3csvg%20viewBox='0%200%2023%2014'%20fill='none'%20xmlns='http://www.w3.org/2000/svg'%3e%3cpath%20d='M20.7482%200H18.8887C21.641%203.93959%2021.6571%2010.0462%2018.8887%2014H20.7482C23.516%2010.0462%2023.4999%203.93959%2020.7482%200Z'%20fill='white'/%3e%3cpath%20d='M2.07027%200C-0.682028%203.93959%20-0.698142%2010.0462%202.07027%2014H3.92985C1.16208%2010.0462%201.1782%203.93959%203.92985%200H2.07027Z'%20fill='white'/%3e%3cpath%20d='M13.4394%202.26107C13.4394%202.63492%2013.7423%202.93787%2014.1162%202.93787H16.6842C16.9858%202.93787%2017.1366%203.30269%2016.9233%203.5154L13.6373%206.8014C13.5103%206.92838%2013.4388%207.10048%2013.4388%207.28032V8.4038C13.4388%208.87111%2013.9022%209.19533%2014.3121%208.97231C14.7298%208.74542%2015.1185%208.47083%2015.4698%208.15628C15.609%208.03188%2015.823%208.03059%2015.9551%208.16338L18.3484%2010.5567C18.4806%2010.6888%2018.4812%2010.9034%2018.3446%2011.0311C16.5295%2012.7295%2014.0898%2013.7698%2011.4077%2013.7698C8.72568%2013.7698%206.286%2012.7295%204.4709%2011.0311C4.33425%2010.9034%204.33489%2010.6888%204.46703%2010.5567L6.86031%208.16338C6.99244%208.03124%207.20644%208.03188%207.34567%208.15628C7.69696%208.47083%208.08563%208.74542%208.50331%208.97231C8.9139%209.19533%209.3767%208.87111%209.3767%208.4038V7.28032C9.3767%207.10048%209.30515%206.92838%209.17817%206.8014L5.89217%203.5154C5.67881%203.30205%205.82964%202.93787%206.1313%202.93787H8.69926C9.07311%202.93787%209.37605%202.63492%209.37605%202.26107V0.568439C9.37605%200.381515%209.52753%200.230042%209.71445%200.230042H13.0991C13.286%200.230042%2013.4375%200.381515%2013.4375%200.568439V2.26107H13.4394Z'%20fill='white'/%3e%3c/svg%3e)Announcing React Compiler Support](https://oxc.rs/blog/2026-08-18-react-compiler-support) [Skip to content](https://oxc.rs/docs/guide/usage/linter/type-aware.html#VPContent) On this page Are you an LLM? You can read better optimized documentation at /docs/guide/usage/linter/type-aware.md for this page in Markdown format # Type-Aware Linting [​](https://oxc.rs/docs/guide/usage/linter/type-aware.html\#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`](https://github.com/oxc-project/tsgolint) and is integrated into the Oxlint CLI and configuration system. Type-aware linting currently supports [59 out of 61](https://github.com/oxc-project/tsgolint/tree/main?tab=readme-ov-file#implemented-rules) type-aware rules from typescript-eslint. Rule coverage, performance, and compatibility continue to improve. ## Overview [​](https://oxc.rs/docs/guide/usage/linter/type-aware.html\#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`](https://github.com/microsoft/typescript-go) and executes type-aware rules, returning structured diagnostics to Oxlint. ## Installation [​](https://oxc.rs/docs/guide/usage/linter/type-aware.html\#installation) Type-aware linting requires an additional dependency: npmpnpmyarnbun sh ``` npm add -D oxlint-tsgolint@latest ``` sh ``` pnpm add -D oxlint-tsgolint@latest ``` sh ``` yarn add -D oxlint-tsgolint@latest ``` sh ``` bun add -D oxlint-tsgolint@latest ``` ## Running type-aware linting [​](https://oxc.rs/docs/guide/usage/linter/type-aware.html\#running-type-aware-linting) You can enable type-aware linting in either place: - CLI flag: `--type-aware` - Root config: `options.typeAware: true` CLI: bash ``` oxlint --type-aware ``` Root config: .oxlintrc.jsonoxlint.config.ts json ``` { "options": { "typeAware": true } } ``` ts ``` import { defineConfig } from "oxlint"; export default defineConfig({ options: { typeAware: true, }, }); ``` When enabled, Oxlint runs standard rules and type-aware rules in the `typescript/*` namespace. `--type-aware` takes precedence over config files. For example, `oxlint --type-aware -c .oxlintrc.json` enables type-aware linting even if that config sets `options.typeAware` to `false`. `options.typeAware` and `options.typeCheck` are only supported in the root config file. Nested configs should not set these fields. In editor and LSP-based integrations like VS Code, type-aware linting can be enabled by setting the `typeAware` option to `true`, see the [Editors](https://oxc.rs/docs/guide/usage/linter/editors.html) page for more information. ### Monorepos and build outputs [​](https://oxc.rs/docs/guide/usage/linter/type-aware.html\#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 bash ``` pnpm install pnpm -r build oxlint --type-aware ``` ### Type checking diagnostics [​](https://oxc.rs/docs/guide/usage/linter/type-aware.html\#type-checking-diagnostics) Enable type checking to report TypeScript errors alongside lint results: bash ``` oxlint --type-aware --type-check ``` Or enable it in the root config: .oxlintrc.jsonoxlint.config.ts json ``` { "options": { "typeAware": true, "typeCheck": true } } ``` ts ``` import { defineConfig } from "oxlint"; export default defineConfig({ options: { typeAware: true, typeCheck: true, }, }); ``` `--type-check` takes precedence over config files. For example, `oxlint --type-check -c .oxlintrc.json` enables type checking even if that config sets `options.typeCheck` to `false`. This mode can replace a separate `tsc --noEmit` step in CI: bash ``` # before tsc --noEmit oxlint # after oxlint --type-aware --type-check ``` ## Configuring type-aware rules [​](https://oxc.rs/docs/guide/usage/linter/type-aware.html\#configuring-type-aware-rules) Type-aware rules are configured like other Oxlint rules. .oxlintrc.jsonoxlint.config.ts json ``` { "plugins": ["typescript"], "rules": { "typescript/no-floating-promises": "error", "typescript/no-unsafe-assignment": "warn" } } ``` ts ``` import { defineConfig } from "oxlint"; export default defineConfig({ plugins: ["typescript"], rules: { "typescript/no-floating-promises": "error", "typescript/no-unsafe-assignment": "warn", }, }); ``` Rules support the same options as their `typescript-eslint` equivalents. .oxlintrc.jsonoxlint.config.ts json ``` { "plugins": ["typescript"], "rules": { "typescript/no-floating-promises": ["error", { "ignoreVoid": true }] } } ``` ts ``` import { defineConfig } from "oxlint"; export default defineConfig({ plugins: ["typescript"], rules: { "typescript/no-floating-promises": ["error", { ignoreVoid: true }], }, }); ``` ## Rule timings [​](https://oxc.rs/docs/guide/usage/linter/type-aware.html\#rule-timings) Use `--debug timings` to find the most expensive rules in your configuration: bash ``` oxlint --type-aware --debug timings ``` The report orders rules by total time and includes their relative share, call count, and execution source: text ``` Rule timings: Rule Time (ms) Relative Calls Source ---------------------------------------------------------- ---------- -------- ----- ---------- typescript/unbound-method 108.620 46.5% 12450 type-aware typescript/no-floating-promises 65.606 28.1% 7327 type-aware eslint/no-unused-vars 2.187 0.9% 372 native typescript/no-duplicate-type-constituents 1.505 0.6% 870 type-aware typescript/no-meaningless-void-operator 1.445 0.6% 383 type-aware vitest/no-standalone-expect 0.978 0.4% 372 native vitest/expect-expect 0.951 0.4% 4682 native typescript/no-implied-eval 0.401 0.2% 13809 type-aware oxc/no-map-spread 0.383 0.2% 12545 native react/no-did-update-set-state 0.382 0.2% 12545 native eslint/no-misleading-character-class 0.380 0.2% 13524 native typescript/no-redundant-type-constituents 0.371 0.2% 870 type-aware unicorn/no-single-promise-in-promise-methods 0.362 0.2% 12545 native eslint/no-useless-backreference 0.360 0.2% 13524 native typescript/no-useless-default-assignment 0.258 0.1% 3110 type-aware eslint/no-console 0.256 0.1% 12484 native eslint/no-caller 0.253 0.1% 11603 native ... ``` `native` rules run inside Oxlint, while rules run by tsgolint are labelled `type-aware`. Timing collection has no overhead unless it is enabled. When enabled, it adds measurement overhead, so use the report to compare rules within the same run rather than as an end-to-end benchmark. ## Disable comments [​](https://oxc.rs/docs/guide/usage/linter/type-aware.html\#disable-comments) Type-aware rules support inline disable comments: ts ``` // oxlint-disable-next-line typescript/no-floating-promises doSomethingAsync(); ``` Report unused disable comments with: bash ``` oxlint --type-aware --report-unused-disable-directives ``` ## TypeScript compatibility [​](https://oxc.rs/docs/guide/usage/linter/type-aware.html\#typescript-compatibility) Type-aware linting is powered by `typescript-go`. - TypeScript **7.0+** is required - Some legacy `tsconfig` options are not supported (like `baseUrl` in `tsconfig.json`) - If you're using config options/features that were deprecated in TypeScript 6.0 or removed in TypeScript 7.0, you'll need to migrate your codebase first - Invalid options are reported when `--type-check` is enabled See the [TypeScript migration guide](https://github.com/microsoft/TypeScript/issues/62508#issuecomment-3348649259) for more details, and consider using [ts5to6](https://github.com/andrewbranch/ts5to6) to upgrade your tsconfig file. ## Stability notes [​](https://oxc.rs/docs/guide/usage/linter/type-aware.html\#stability-notes) Type-aware linting: - Rule coverage is incomplete (but very close) - Very large codebases may encounter high memory usage - Performance continues to improve ## Troubleshooting [​](https://oxc.rs/docs/guide/usage/linter/type-aware.html\#troubleshooting) ### Performance and debugging [​](https://oxc.rs/docs/guide/usage/linter/type-aware.html\#performance-and-debugging) If type-aware linting is slow or uses excessive memory: 1. Update both tools: - `oxlint` - `oxlint-tsgolint` 2. Enable debug logging: bash ``` OXC_LOG=debug oxlint --type-aware ``` Example output (showing key timing milestones): ``` 2026/01/01 12:00:00.000000 Starting tsgolint 2026/01/01 12:00:00.001000 Starting to assign files to programs. Total files: 259 2026/01/01 12:00:01.000000 Done assigning files to programs. Total programs: 8. Unmatched files: 75 2026/01/01 12:00:01.001000 Starting linter with 12 workers 2026/01/01 12:00:01.001000 Workload distribution: 8 programs 2026/01/01 12:00:01.002000 [1/8] Running linter on program: /path/to/project/jsconfig.json ... 2026/01/01 12:00:01.100000 [4/8] Running linter on program: /path/to/project/tsconfig.json 2026/01/01 12:00:02.500000 Program created with 26140 source files 2026/01/01 12:00:14.000000 /path/to/project/oxlint-plugin.mts ... 2026/01/01 12:00:14.100000 [5/8] Running linter on program: /path/to/project/apps/tsconfig.json ... 2026/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. ### Common performance issues [​](https://oxc.rs/docs/guide/usage/linter/type-aware.html\#common-performance-issues) #### Root tsconfig includes too many files [​](https://oxc.rs/docs/guide/usage/linter/type-aware.html\#root-tsconfig-includes-too-many-files) A root `tsconfig.json` with overly broad `include` patterns can inadvertently include all files in the repository, causing significant slowdowns: tsconfig.json json ``` { "include": ["**/*"] // ❌ Catches everything } ``` This configuration pulls in build outputs and other files that shouldn't be type-checked. **Fix:** Explicitly scope the `include` patterns and add appropriate `exclude` entries: tsconfig.json json ``` { "include": ["src/**/*"], // ✅ Only source files "exclude": ["dist", "build", "coverage"] // node_modules are excluded by default } ``` For monorepos, ensure the root `tsconfig.json` does not include source files directly: tsconfig.json json ``` { "files": [] } ``` **Diagnosing the issue:** Enable debug logging and look for programs with an unusually high number of source files: ``` 2026/01/01 12:00:02.500000 Program created with 26140 source files ``` If you see thousands of files in a single program, check that tsconfig's `include`/`exclude` settings. ## Next steps [​](https://oxc.rs/docs/guide/usage/linter/type-aware.html\#next-steps) - Check [implemented rules](https://github.com/oxc-project/tsgolint/tree/main?tab=readme-ov-file#implemented-rules) - Report issues to [https://github.com/oxc-project/tsgolint](https://github.com/oxc-project/tsgolint) --- ## Agent Navigation ### Machine endpoints - Knowledge graph: https://pyweb.dev/api/graph.json - Graph analysis: https://pyweb.dev/api/graph-analysis.json - Context index: https://pyweb.dev/llms.txt