From 21c26546caedbc3b56b6d8778ff53913274fa42d Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Thu, 26 Aug 2021 21:44:52 +0800 Subject: [PATCH 1/3] docs: document tsconfig options that may affect the compilation result closes #4639 closes #4727 --- docs/guide/features.md | 34 +++++++++++++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/docs/guide/features.md b/docs/guide/features.md index dd7d649f8eb014..011b417dc30763 100644 --- a/docs/guide/features.md +++ b/docs/guide/features.md @@ -34,7 +34,39 @@ Vite only performs transpilation on `.ts` files and does **NOT** perform type ch Vite uses [esbuild](https://github.com/evanw/esbuild) to transpile TypeScript into JavaScript which is about 20~30x faster than vanilla `tsc`, and HMR updates can reflect in the browser in under 50ms. -Note that because `esbuild` only performs transpilation without type information, it doesn't support certain features like const enum and implicit type-only imports. You must set `"isolatedModules": true` in your `tsconfig.json` under `compilerOptions` so that TS will warn you against the features that do not work with isolated transpilation. +### TypeScript Compiler Options + +Some configuration fields under `compilerOptions` in `tsconfig.json` require special attention. + +#### `isolatedModules` + +Should be set to `true`. + +It is because `esbuild` only performs transpilation without type information, it doesn't support certain features like const enum and implicit type-only imports. + +You must set `"isolatedModules": true` in your `tsconfig.json` under `compilerOptions`, so that TS will warn you against the features that do not work with isolated transpilation. + +#### `useDefineForClassFields` + +Starting from Vite 2.5.0, the default value will be `true` if the TypeScript target is `ESNext`. It is consistent with the behavior of `tsc` 4.3.2 and later. + +This is because it is the standard ECMAScript runtime behavior. + +But it may be counter-intuitive for those coming from other programming languages or older versions of TypeScript. +You can read more about the transition in the [TypeScript 3.7 release notes](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#the-usedefineforclassfields-flag-and-the-declare-property-modifier). + +If you are using a library that heavily relies on class fields, please be careful about the library's intended usage of it. + +Most libraries expect `"useDefineForClassFields": true`, such as [MobX](https://mobx.js.org/installation.html#use-spec-compliant-transpilation-for-class-properties), [Vue Class Components 8.x](https://github.com/vuejs/vue-class-component/issues/465), etc. + +But some libraries haven't transitioned to this new default yet, including [`lit-element`](https://github.com/lit/lit-element/issues/1030). If you are using such libraries, please explicitly set `useDefineForClassFields` to `false`. + +#### Other Compiler Options Affecting the Build Result + +- [`extends`](https://www.typescriptlang.org/tsconfig#extends) +- [`importsNotUsedAsValues`](https://www.typescriptlang.org/tsconfig#importsNotUsedAsValues) +- [`jsxFactory`](https://www.typescriptlang.org/tsconfig#jsxFactory) +- [`jsxFragmentFactory`](https://www.typescriptlang.org/tsconfig#jsxFragmentFactory) ### Client Types From 840539ca388dd7c3ce0f76c5e1f6fe1bd3619800 Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Thu, 26 Aug 2021 21:50:00 +0800 Subject: [PATCH 2/3] docs: add link to the TypeScript PR --- docs/guide/features.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/features.md b/docs/guide/features.md index 011b417dc30763..a61e643cd3e147 100644 --- a/docs/guide/features.md +++ b/docs/guide/features.md @@ -48,7 +48,7 @@ You must set `"isolatedModules": true` in your `tsconfig.json` under `compilerOp #### `useDefineForClassFields` -Starting from Vite 2.5.0, the default value will be `true` if the TypeScript target is `ESNext`. It is consistent with the behavior of `tsc` 4.3.2 and later. +Starting from Vite 2.5.0, the default value will be `true` if the TypeScript target is `ESNext`. It is consistent with the [behavior of `tsc` 4.3.2 and later](https://github.com/microsoft/TypeScript/pull/42663). This is because it is the standard ECMAScript runtime behavior. From ae72ee787ed54c579681f8c7d826f71d24818c39 Mon Sep 17 00:00:00 2001 From: Haoqun Jiang Date: Thu, 26 Aug 2021 21:53:14 +0800 Subject: [PATCH 3/3] docs: some rewording --- docs/guide/features.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/guide/features.md b/docs/guide/features.md index a61e643cd3e147..972f41dee15967 100644 --- a/docs/guide/features.md +++ b/docs/guide/features.md @@ -48,9 +48,7 @@ You must set `"isolatedModules": true` in your `tsconfig.json` under `compilerOp #### `useDefineForClassFields` -Starting from Vite 2.5.0, the default value will be `true` if the TypeScript target is `ESNext`. It is consistent with the [behavior of `tsc` 4.3.2 and later](https://github.com/microsoft/TypeScript/pull/42663). - -This is because it is the standard ECMAScript runtime behavior. +Starting from Vite 2.5.0, the default value will be `true` if the TypeScript target is `ESNext`. It is consistent with the [behavior of `tsc` 4.3.2 and later](https://github.com/microsoft/TypeScript/pull/42663). It is also the standard ECMAScript runtime behavior. But it may be counter-intuitive for those coming from other programming languages or older versions of TypeScript. You can read more about the transition in the [TypeScript 3.7 release notes](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#the-usedefineforclassfields-flag-and-the-declare-property-modifier). @@ -59,7 +57,7 @@ If you are using a library that heavily relies on class fields, please be carefu Most libraries expect `"useDefineForClassFields": true`, such as [MobX](https://mobx.js.org/installation.html#use-spec-compliant-transpilation-for-class-properties), [Vue Class Components 8.x](https://github.com/vuejs/vue-class-component/issues/465), etc. -But some libraries haven't transitioned to this new default yet, including [`lit-element`](https://github.com/lit/lit-element/issues/1030). If you are using such libraries, please explicitly set `useDefineForClassFields` to `false`. +But a few libraries haven't transitioned to this new default yet, including [`lit-element`](https://github.com/lit/lit-element/issues/1030). Please explicitly set `useDefineForClassFields` to `false` in these cases. #### Other Compiler Options Affecting the Build Result