From 54d10af1fd57f17bc1d035925cc0127d75260099 Mon Sep 17 00:00:00 2001
From: Aaron <aaronklinker1@gmail.com>
Date: Sun, 26 Jul 2026 11:49:41 -0500
Subject: [PATCH] fix(TS)!: Update `.wxt/tsconfig.json` compiler options,
 require TS >=5.4 (#2512)

BREAKING CHANGE: Updates `.wxt/tsconfig.json` defaults to latest recommended settings for vite projects and requires Typescript 5.4 or later. See #2512 for details on what compiler options were changed.

Co-authored-by: cookesan <cookesan@users.noreply.github.com>
---
 .../wxt/e2e/tests/typescript-project.test.ts  | 48 ++++++++++++++-----
 packages/wxt/package.json                     |  6 ++-
 packages/wxt/src/core/generate-wxt-dir.ts     | 16 +++++--
 3 files changed, 53 insertions(+), 17 deletions(-)

diff --git a/packages/wxt/e2e/tests/typescript-project.test.ts b/packages/wxt/e2e/tests/typescript-project.test.ts
index 673783ca..389502f3 100644
--- a/packages/wxt/e2e/tests/typescript-project.test.ts
+++ b/packages/wxt/e2e/tests/typescript-project.test.ts
@@ -324,15 +324,23 @@ describe('TypeScript Project', () => {
       ----------------------------------------
       {
         "compilerOptions": {
+          "lib": [
+            "ESNext",
+            "DOM",
+            "DOM.Iterable"
+          ],
           "target": "ESNext",
-          "module": "ESNext",
+          "module": "Preserve",
+          "moduleDetection": "force",
           "moduleResolution": "Bundler",
+          "allowImportingTsExtensions": true,
+          "verbatimModuleSyntax": true,
           "noEmit": true,
-          "esModuleInterop": true,
-          "forceConsistentCasingInFileNames": true,
-          "resolveJsonModule": true,
           "strict": true,
           "skipLibCheck": true,
+          "noFallthroughCasesInSwitch": true,
+          "noUncheckedIndexedAccess": true,
+          "noImplicitOverride": true,
           "paths": {
             "@": [
               ".."
@@ -406,15 +414,23 @@ describe('TypeScript Project', () => {
       ----------------------------------------
       {
         "compilerOptions": {
+          "lib": [
+            "ESNext",
+            "DOM",
+            "DOM.Iterable"
+          ],
           "target": "ESNext",
-          "module": "ESNext",
+          "module": "Preserve",
+          "moduleDetection": "force",
           "moduleResolution": "Bundler",
+          "allowImportingTsExtensions": true,
+          "verbatimModuleSyntax": true,
           "noEmit": true,
-          "esModuleInterop": true,
-          "forceConsistentCasingInFileNames": true,
-          "resolveJsonModule": true,
           "strict": true,
           "skipLibCheck": true,
+          "noFallthroughCasesInSwitch": true,
+          "noUncheckedIndexedAccess": true,
+          "noImplicitOverride": true,
           "paths": {
             "@": [
               "../src"
@@ -473,15 +489,23 @@ describe('TypeScript Project', () => {
       ----------------------------------------
       {
         "compilerOptions": {
+          "lib": [
+            "ESNext",
+            "DOM",
+            "DOM.Iterable"
+          ],
           "target": "ESNext",
-          "module": "ESNext",
+          "module": "Preserve",
+          "moduleDetection": "force",
           "moduleResolution": "Bundler",
+          "allowImportingTsExtensions": true,
+          "verbatimModuleSyntax": true,
           "noEmit": true,
-          "esModuleInterop": true,
-          "forceConsistentCasingInFileNames": true,
-          "resolveJsonModule": true,
           "strict": true,
           "skipLibCheck": true,
+          "noFallthroughCasesInSwitch": true,
+          "noUncheckedIndexedAccess": true,
+          "noImplicitOverride": true,
           "paths": {
             "example": [
               "../example"
diff --git a/packages/wxt/package.json b/packages/wxt/package.json
index 595186cc..7e5c9130 100644
--- a/packages/wxt/package.json
+++ b/packages/wxt/package.json
@@ -58,7 +58,8 @@
   "peerDependencies": {
     "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0",
     "vite": "^6.3.4 || ^7.0.0 || ^8.0.0-0",
-    "web-ext": ">=9.2.0"
+    "web-ext": ">=9.2.0",
+    "typescript": ">=5.4"
   },
   "peerDependenciesMeta": {
     "eslint": {
@@ -66,6 +67,9 @@
     },
     "web-ext": {
       "optional": true
+    },
+    "typescript": {
+      "optional": true
     }
   },
   "devDependencies": {
diff --git a/packages/wxt/src/core/generate-wxt-dir.ts b/packages/wxt/src/core/generate-wxt-dir.ts
index 05083b98..8364afaf 100644
--- a/packages/wxt/src/core/generate-wxt-dir.ts
+++ b/packages/wxt/src/core/generate-wxt-dir.ts
@@ -297,15 +297,23 @@ async function getTsConfigEntry(): Promise<WxtDirFileEntry> {
 
   const tsconfig = {
     compilerOptions: {
+      // Environment setup & latest features
+      lib: ['ESNext', 'DOM', 'DOM.Iterable'],
       target: 'ESNext',
-      module: 'ESNext',
+      module: 'Preserve',
+      moduleDetection: 'force',
+      // Bundler mode
       moduleResolution: 'Bundler',
+      allowImportingTsExtensions: true,
+      verbatimModuleSyntax: true,
       noEmit: true,
-      esModuleInterop: true,
-      forceConsistentCasingInFileNames: true,
-      resolveJsonModule: true,
+      // Best practices
       strict: true,
       skipLibCheck: true,
+      noFallthroughCasesInSwitch: true,
+      noUncheckedIndexedAccess: true,
+      noImplicitOverride: true,
+      // Project settings
       paths,
     },
     include: [`${getTsconfigPath(wxt.config.root)}/**/*`, './wxt.d.ts'],