feat!: adapt for TypeScript 5.0

README.md

@@ -2,30 +2,87 @@
 
 TSConfigs for Vue projects to extend.
 
-Requires TypeScript >= 4.5.
+Requires TypeScript >= 5.0. For TypeScript v4.5 to v4.9, please use [v0.1.x](https://www.npmjs.com/package/@vue/tsconfig/v/0.1.3).
 
-Install:
+[See below for the changes in v0.2.x.](#migrating-from-typescript--50)
+
+## Installation
 
 ```sh
 npm add -D @vue/tsconfig
 ```
 
+## Usage
+
 Add one of the available configurations to your `tsconfig.json`:
 
-The base configuration (runtime-agnostic):
+### The Base Configuration (Runtime-agnostic)
 
 ```json
-"extends": "@vue/tsconfig/tsconfig.json"
+"extends": "@vue/tsconfig"
 ```
 
-Configuration for Browser environment:
+### Configuration for Browser Environment
 
 ```json
-"extends": "@vue/tsconfig/tsconfig.web.json"
+"extends": [
+  "@vue/tsconfig",
+  "@vue/tsconfig/tsconfig.dom.json"
+]
+```
+
+### Configuration for Node Environments
+
+First install the base tsconfig and types for the Node.js version you are targeting, for example:
+
+```sh
+npm add -D @tsconfig/node18 @types/node@18
 ```
 
-Configuration for Node environment:
+Then extend the Node.js tsconfig and the Vue tsconfig in your `tsconfig.json`:
 
 ```json
-"extends": "@vue/tsconfig/tsconfig.node.json"
+"extends": [
+  "@tsconfig/node18/tsconfig.json",
+  "@vue/tsconfig"
+],
+"compilerOptions": [
+  "types": ["node"]
+]
 ```
+
+Make sure to place `@vue/tsconfig` *after* `@tsconfig/node18` so that it takes precedence.
+
+## Migrating from TypeScript < 5.0
+
+- The usage of base `tsconfig.json` is unchanged.
+- `tsconfig.web.json` is now renamed to `tsconfig.dom.json`, to align with `@vue/runtime-dom` and `@vue/compiler-dom`, and it only contains dom-specific options, you need to use it in conjunction with the base `tsconfig.json`:
+
+  ```json
+  "extends": [
+    "@vue/tsconfig",
+    "@vue/tsconfig/tsconfig.dom.json"
+  ]
+  ```
+
+- `tsconfig.node.json` is removed, please read the [Node.js section](#configuration-for-node-environments) above for Node.js usage.
+
+Some configurations have been updated, which might affect your projects:
+
+- `moduleResolution` changed from `node` to [`bundler`](https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/#moduleresolution-bundler)
+- The `lib` option in `tsconfig.web.json` now includes `ES2020` by default.
+  - Previously it was ES2016, which was the lowest ES version that Vue 3 supports.
+  - Vite 4 transpiles down to ES2020 by default, this new default is to align with the build tool.
+  - This change won't throw any new errors on your existing code, but if you are targeting old browsers and want TypeScript to throw errors on newer features used, you can override the `lib` option in your `tsconfig.json`:
+
+    ```json
+    {
+      "extends": [
+        "@vue/tsconfig",
+        "@vue/tsconfig/tsconfig.dom.json"
+      ],
+      "compilerOptions": {
+        "lib": ["ES2016", "DOM", "DOM.Iterable"]
+      }
+    }
+    ```

package.json

@@ -20,14 +20,6 @@
     "url": "https://github.com/vuejs/tsconfig/issues"
   },
   "homepage": "https://github.com/vuejs/tsconfig#readme",
-  "peerDependencies": {
-    "@types/node": "*"
-  },
-  "peerDependenciesMeta": {
-    "@types/node": {
-      "optional": true
-    }
-  },
   "publishConfig": {
     "access": "public"
   }

tsconfig.web.json → tsconfig.dom.json

@@ -1,19 +1,21 @@
 {
-  "extends": "./tsconfig.json",
   "compilerOptions": {
     "lib": [
-      // Should target at least ES2016 in Vue 3
+      // Target ES2020 to align with Vite.
+      // <https://vitejs.dev/config/build-options.html#build-target>
       // Support for newer versions of language built-ins are
       // left for the users to include, because that would require:
       //   - either the project doesn't need to support older versions of browsers;
       //   - or the project has properly included the necessary polyfills.
-      "ES2016",
+      "ES2020",
 
       "DOM",
       "DOM.Iterable"
 
       // No `ScriptHost` because Vue 3 dropped support for IE
     ],
+
+    // Set to empty to avoid accidental inclusion of unwanted types
     "types": []
   }
 }

tsconfig.json

@@ -1,8 +1,15 @@
 {
   "compilerOptions": {
+    // As long as you are using a build tool, we recommend you to author and ship in ES modules.
+    // Even if you are targeting Node.js, because
+    //  - `CommonJS` is too outdated
+    //  - the ecosystem hasn't fully caught up with `Node16`/`NodeNext`
+    // This recommendation includes environments like Vitest, Vite Config File, Vite SSR, etc.
     "module": "ESNext",
-    "moduleResolution": "Node",
+
+    "moduleResolution": "bundler",
     "resolveJsonModule": true,
+    "allowImportingTsExtensions": true,
     "useDefineForClassFields": true,
 
     // Required in Vue projects
@@ -16,11 +23,11 @@
 
     // Required in Vite
     "isolatedModules": true,
-    // For `<script setup>`
-    // See <https://devblogs.microsoft.com/typescript/announcing-typescript-4-5-beta/#preserve-value-imports>
-    "preserveValueImports": true,
-    // Enforce using `import type` instead of `import` for types
-    "importsNotUsedAsValues": "error",
+
+    // <https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/#verbatimmodulesyntax>
+    // Any imports or exports without a type modifier are left around. This is important for `<script setup>`.
+    // Anything that uses the type modifier is dropped entirely.
+    "verbatimModuleSyntax": true,
 
     // A few notes:
     // - Vue 3 supports ES2016+