feat(parser): add onUnsupportedTypeScriptVersion option to error on unsupported TypeScript versions by zaewc · Pull Request #12465 · typescript-eslint/typescript-eslint

zaewc · 2026-06-30T11:02:14Z

PR Checklist

Addresses an existing open issue: fixes Enhancement: configuration option to error on unsupported TypeScript version (onUnsupportedTypeScriptVersion=error) #10092
That issue was marked as accepting prs
Steps in Contributing were taken

Overview

Adds a new onUnsupportedTypeScriptVersion parser option that controls how the parser reacts when run with a TypeScript version that isn't officially supported. It accepts:

'warn' (default) - log the warning to the console (existing behavior)
'error' - log the message and throw, so the lint run fails. This is the use case from the issue: catching unsupported TypeScript versions in CI (e.g. a Dependabot/Renovate bump) where warnings go unnoticed and only non-zero exit codes are detected
'ignore' - ignore

The default stays 'warn', so this is a non-breaking, opt-in change

notes

@typescript-eslint/types: added onUnsupportedTypeScriptVersion to ParserOptions and marked warnOnUnsupportedTypeScriptVersion as @deprecated
@typescript-eslint/typescript-estree: added the option to TSESTreeOptions, and reworked warnAboutTSVersion -> handleUnsupportedTSVersion to branch on warn/error/ignore. 'error' throws regardless of TTY/loggerFn, since the CI scenario this targets is non-TTY
@typescript-eslint/parser: maps the option through, falling back to the deprecated warnOnUnsupportedTypeScriptVersion boolean when the new option isn't set (true -> 'warn', false -> 'ignore'). onUnsupportedTypeScriptVersion takes precedence when both are provided

warnOnUnsupportedTypeScriptVersion continues to work, it's deprecated but still respected == No default behavior changes

docs & tests

Documented the new option (and deprecated the old one) in Parser.mdx and Dependency_Versions.mdx
Added tests covering warn/error/ignore behavior and the precedence of the new option over the deprecated boolean

typescript-eslint · 2026-06-30T11:02:18Z

Thanks for the PR, @zaewc!

typescript-eslint is a 100% community driven project, and we are incredibly grateful that you are contributing to that community.

The core maintainers work on this in their personal time, so please understand that it may not be possible for them to review your work immediately.

Thanks again!

🙏 Please, if you or your company is finding typescript-eslint valuable, help us sustain the project by sponsoring it transparently on https://opencollective.com/typescript-eslint.

netlify · 2026-06-30T11:02:24Z

❌ Deploy Preview for typescript-eslint failed.

Name	Link
🔨 Latest commit	`84777db`
🔍 Latest deploy log	https://app.netlify.com/projects/typescript-eslint/deploys/6a55fac924d08e0008c6eaec

nx-cloud · 2026-06-30T11:03:36Z

🤖 Nx Cloud AI Fix Eligible

An automatically generated fix could have helped fix failing tasks for this run, but Self-healing CI is disabled for this workspace. Visit workspace settings to enable it and get automatic fixes in future runs.

_{To disable these notifications, a workspace admin can disable them in workspace settings.}

View your CI Pipeline Execution ↗ for commit bf0bab9

Command	Status	Duration	Result
`nx run-many --target=build --parallel --exclude...`	❌ Failed	14s	View ↗

💡 Dealing with memory or CPU issues? See memory and CPU details with the resource usage add-on ↗.

☁️ Nx Cloud last updated this comment at 2026-07-14 09:02:05 UTC

zaewc · 2026-06-30T11:15:09Z

The Build All Packages job failed, but I believe it's a stale Nx Cloud cache rather than a real type error, and could use a maintainer re-run. 🙏

In the failing run, the task table shows types:build as a Remote Cache Hit while typescript-estree:build rebuilt fresh. The cached types artifact predates the new onUnsupportedTypeScriptVersion field, so in packages/parser/src/parser.ts the access parserOptions.onUnsupportedTypeScriptVersion falls through to the [additionalProperties: string]: unknown index signature on ParserOptions. That makes unknown ?? 'warn' resolve to {} | 'warn' | 'ignore', which produces:

src/parser.ts:130:5 - error TS2322: Type '{}' is not assignable to type '"error" | "ignore" | "warn" | undefined'.

The other two reported errors cascade from the same stale types output.

Locally, after clearing all dist/.tsbuildinfo and running a no-cache build of the affected packages, everything compiles cleanly:

nx run-many -t build -p types typescript-estree scope-manager utils parser --skip-nx-cache
→ NX  Successfully ran target build for 5 projects

So a fresh types:build (with the new field) resolves it. Could a maintainer re-run the CI workflow? If a stale-cache re-run isn't enough, I'm happy to push a small change to types to force a cache miss. Thanks!

JoshuaKGoldberg

A good start, I like the direction & docs! Requesting changes on the throwing behavior. Thanks! ✨

JoshuaKGoldberg · 2026-07-01T12:38:53Z

+:::caution Deprecated
+Use [`onUnsupportedTypeScriptVersion`](#onunsupportedtypescriptversion) instead.
+`true` is equivalent to `'warn'` and `false` is equivalent to `'ignore'`.
+If both options are provided, `onUnsupportedTypeScriptVersion` takes precedence.


[Feature] Let's throw an error if both are provided. That's an invalid config and we don't want to have to support that. We've had issues in the past where folks expected technically-invalid configs to run and were surprised when they didn't.

Done 0c44b7c

parseForESLint now throws when both onUnsupportedTypeScriptVersion and the deprecated warnOnUnsupportedTypeScriptVersion are set, instead of silently picking one. Updated the docs and tests to match.

Thanks 💖

JoshuaKGoldberg · 2026-07-01T12:41:22Z

[Praise] Great docs 🙂

JoshuaKGoldberg · 2026-07-01T13:01:24Z

Re the builds: odd. I merged the latest master in and rebuilt. It builds locally for me just fine. This might be an issue with our Nx setup. Cc @JamesHenry

… deprecated warnOnUnsupportedTypeScriptVersion are provided

codecov · 2026-07-12T14:44:46Z

Codecov Report

❌ Patch coverage is 90.00000% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 86.91%. Comparing base (c4d9c73) to head (c3f4306).
⚠️ Report is 7 commits behind head on main.

⚠️ Current head c3f4306 differs from pull request most recent head 84777db

Please upload reports for the commit 84777db to get more accurate results.

Files with missing lines	Patch %	Lines
...ipt-estree/src/parseSettings/warnAboutTSVersion.ts	87.50%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #12465      +/-   ##
==========================================
- Coverage   87.06%   86.91%   -0.15%     
==========================================
  Files         515      511       -4     
  Lines       16643    16450     -193     
  Branches     5204     5203       -1     
==========================================
- Hits        14490    14298     -192     
+ Misses       1462     1460       -2     
- Partials      691      692       +1

Flag	Coverage Δ
unittest	`86.91% <90.00%> (-0.15%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...pt-estree/src/parseSettings/createParseSettings.ts	`85.52% <100.00%> (+0.19%)`	⬆️
...ipt-estree/src/parseSettings/warnAboutTSVersion.ts	`83.33% <87.50%> (-9.53%)`	⬇️

... and 4 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

zaewc · 2026-07-12T14:45:58Z

@JoshuaKGoldberg @StyleShit

Only types overrides its build inputs to src/generated/**, so other src changes didn't bust the cache -> CI kept building the parser against a stale types

Removing that override fixed it. happy to revert if it was there for a reason

JoshuaKGoldberg

LGTM, thanks! ✨

Just a couple of small touchups that we can always apply before merge. Happy to do them tomorrow before the weekly release.

JoshuaKGoldberg · 2026-07-12T17:03:18Z

          "copy-ast-spec"
-        ],
-        "inputs": [
-          "{projectRoot}/src/generated/**/*"


This might be correct, but let's just switch it out to a separate change. We as maintainers can verify this PR works on our local builds. Fiddling with the Nx setup can be very finnicky.

Suggested change

"{projectRoot}/src/generated/**/*"

],

"inputs": [

"{projectRoot}/src/generated/**/*"

Back-linking to where this was also added in an unrelated PR (which reinforces my hesitation): https://github.com/typescript-eslint/typescript-eslint/pull/11355/changes#r2347376398

73b7c43 I reverted!

…st.ts Co-authored-by: Josh Goldberg ✨ <github@joshuakgoldberg.com>

Co-authored-by: Josh Goldberg ✨ <github@joshuakgoldberg.com>

This reverts commit c3f4306. Keeping the Nx setup change out of this PR per review; the parser change is verified on local builds.

StyleShit

Added some non-blocking documentation and typing stuff

Co-authored-by: Evyatar Daud <32631382+StyleShit@users.noreply.github.com>

…e function

JoshuaKGoldberg

Build failures still don't happen locally for me. 🚢

Thanks for all the iteration & work on this @zaewc!

SchroederSteffen · 2026-07-21T07:35:08Z

  projectFolderIgnoreList?: string[];
  projectService?: boolean | ProjectServiceOptions;
  tsconfigRootDir?: string;
  warnOnUnsupportedTypeScriptVersion?: boolean;


Thanks for this new option, I'm about to enable it in my projects.
But I noticed that it's missing in this overview at the top.

…nsupported TypeScript versions (typescript-eslint#12465) * feat(types): add onUnsupportedTypeScriptVersion parser option * feat(typescript-estree): support onUnsupportedTypeScriptVersion behavior * feat(parser): map onUnsupportedTypeScriptVersion and deprecated boolean * test: cover onUnsupportedTypeScriptVersion warn/error/ignore behavior * docs: document onUnsupportedTypeScriptVersion option * fix(parser): suppress no-deprecated for backwards-compat option read * fix(parser): throw error when both onUnsupportedTypeScriptVersion and deprecated warnOnUnsupportedTypeScriptVersion are provided * chore: remove unused inputs * Update packages/typescript-estree/tests/lib/warn-on-unsupported-ts.test.ts Co-authored-by: Josh Goldberg ✨ <github@joshuakgoldberg.com> * Update packages/typescript-estree/tests/lib/warn-on-unsupported-ts.test.ts Co-authored-by: Josh Goldberg ✨ <github@joshuakgoldberg.com> * Update docs/packages/Parser.mdx Co-authored-by: Josh Goldberg ✨ <github@joshuakgoldberg.com> * Revert "chore: remove unused inputs" This reverts commit c3f4306. Keeping the Nx setup change out of this PR per review; the parser change is verified on local builds. * Update docs/packages/Parser.mdx Co-authored-by: Evyatar Daud <32631382+StyleShit@users.noreply.github.com> * Update docs/users/Dependency_Versions.mdx Co-authored-by: Evyatar Daud <32631382+StyleShit@users.noreply.github.com> * fix: standardize severity argument in buildUnsupportedTSVersionMessage function --------- Co-authored-by: Josh Goldberg ✨ <git@joshuakgoldberg.com> Co-authored-by: Evyatar Daud <32631382+StyleShit@users.noreply.github.com> Co-authored-by: Josh Goldberg ✨ <github@joshuakgoldberg.com>

zaewc added 6 commits June 30, 2026 19:37

feat(types): add onUnsupportedTypeScriptVersion parser option

29b917a

feat(typescript-estree): support onUnsupportedTypeScriptVersion behavior

6b87f54

feat(parser): map onUnsupportedTypeScriptVersion and deprecated boolean

ccc288b

test: cover onUnsupportedTypeScriptVersion warn/error/ignore behavior

777ebf9

docs: document onUnsupportedTypeScriptVersion option

a2d79a7

fix(parser): suppress no-deprecated for backwards-compat option read

0e5a4ac

zaewc changed the title ~~Feat/on unsupported typescript version~~ feat(parser): add onUnsupportedTypeScriptVersion option to error on unsupported TypeScript versions Jun 30, 2026

Merge branch 'main' into feat/on-unsupported-typescript-version

819afb5

JoshuaKGoldberg requested changes Jul 1, 2026

View reviewed changes

JoshuaKGoldberg added the awaiting response Issues waiting for a reply from the OP or another party label Jul 1, 2026

zaewc and others added 4 commits July 2, 2026 11:47

fix(parser): throw error when both onUnsupportedTypeScriptVersion and…

0c44b7c

… deprecated warnOnUnsupportedTypeScriptVersion are provided

Merge branch 'main' into feat/on-unsupported-typescript-version

b17f5e1

Merge branch 'main' into feat/on-unsupported-typescript-version

9c53e55

chore: remove unused inputs

c3f4306

JoshuaKGoldberg previously approved these changes Jul 12, 2026

View reviewed changes

Update packages/typescript-estree/tests/lib/warn-on-unsupported-ts.te…

2ec6d83

…st.ts Co-authored-by: Josh Goldberg ✨ <github@joshuakgoldberg.com>

zaewc dismissed JoshuaKGoldberg’s stale review via 2ec6d83 July 13, 2026 08:13

zaewc and others added 3 commits July 13, 2026 17:13

Update packages/typescript-estree/tests/lib/warn-on-unsupported-ts.te…

af2f1e8

…st.ts Co-authored-by: Josh Goldberg ✨ <github@joshuakgoldberg.com>

Update docs/packages/Parser.mdx

52a3bd3

Co-authored-by: Josh Goldberg ✨ <github@joshuakgoldberg.com>

Revert "chore: remove unused inputs"

73b7c43

This reverts commit c3f4306. Keeping the Nx setup change out of this PR per review; the parser change is verified on local builds.

zaewc requested a review from JoshuaKGoldberg July 13, 2026 08:16

github-actions Bot removed the awaiting response Issues waiting for a reply from the OP or another party label Jul 13, 2026

StyleShit reviewed Jul 13, 2026

View reviewed changes

Comment thread docs/packages/Parser.mdx Outdated

Comment thread docs/users/Dependency_Versions.mdx Outdated

Comment thread packages/typescript-estree/src/parseSettings/warnAboutTSVersion.ts Outdated

zaewc and others added 3 commits July 14, 2026 17:57

Update docs/packages/Parser.mdx

5cbd4b0

Co-authored-by: Evyatar Daud <32631382+StyleShit@users.noreply.github.com>

Update docs/users/Dependency_Versions.mdx

bf0bab9

Co-authored-by: Evyatar Daud <32631382+StyleShit@users.noreply.github.com>

fix: standardize severity argument in buildUnsupportedTSVersionMessag…

84777db

…e function

zaewc requested a review from StyleShit July 14, 2026 09:01

StyleShit approved these changes Jul 14, 2026

View reviewed changes

StyleShit added the 1 approval >=1 team member has approved this PR; we're now leaving it open for more reviews before we merge label Jul 14, 2026

JoshuaKGoldberg approved these changes Jul 18, 2026

View reviewed changes

JoshuaKGoldberg merged commit d8f1044 into typescript-eslint:main Jul 18, 2026
20 of 26 checks passed

SchroederSteffen reviewed Jul 21, 2026

View reviewed changes

SchroederSteffen mentioned this pull request Jul 21, 2026

fix(website): list onUnsupportedTypeScriptVersion in parser options #12585

Merged

3 of 4 tasks

github-actions Bot mentioned this pull request Aug 3, 2026

chore(deps): update typescript-eslint monorepo to v8.65.0 victoraugustoas/finance-manager#94

Merged

1 task

This was referenced Oct 22, 2026

［Historical PR］ deps（npm）: bump typescript-eslint from 8.63.0 to 8.65.0 in /web/client rennerdo30/bifrost-proxy#208

Closed

［Historical PR］ deps（npm）: bump typescript-eslint from 8.64.0 to 8.65.0 in /web/server rennerdo30/bifrost-proxy#217

Closed

mtrezza mentioned this pull request Oct 26, 2026

refactor: Bump typescript-eslint from 8.64.0 to 8.66.0 parse-community/parse-server-example#957

Merged

Conversation

zaewc commented Jun 30, 2026

PR Checklist

Overview

notes

docs & tests

Uh oh!

typescript-eslint Bot commented Jun 30, 2026

Uh oh!

netlify Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

❌ Deploy Preview for typescript-eslint failed.

Uh oh!

nx-cloud Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 Nx Cloud AI Fix Eligible

Uh oh!

zaewc commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JoshuaKGoldberg left a comment

Choose a reason for hiding this comment

Uh oh!

JoshuaKGoldberg Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

zaewc Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

JoshuaKGoldberg Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

JoshuaKGoldberg commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Jul 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

zaewc commented Jul 12, 2026

Uh oh!

JoshuaKGoldberg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

JoshuaKGoldberg Jul 12, 2026

Choose a reason for hiding this comment

Uh oh!

zaewc Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

StyleShit left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JoshuaKGoldberg left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

SchroederSteffen Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SchroederSteffen Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

netlify Bot commented Jun 30, 2026 •

edited

Loading

nx-cloud Bot commented Jun 30, 2026 •

edited

Loading

zaewc commented Jun 30, 2026 •

edited

Loading

JoshuaKGoldberg commented Jul 1, 2026 •

edited

Loading

codecov Bot commented Jul 12, 2026 •

edited

Loading

StyleShit left a comment •

edited

Loading

JoshuaKGoldberg left a comment •

edited

Loading

SchroederSteffen Jul 21, 2026 •

edited

Loading