docs: add onlyRemoveTypeImports to (preset|plugin-transform)typ… (#2185)

* docs: add onlyRemoveTypeImports to (preset|plugin-transform)typescript

* Backport doc updates

* Fix formatting for option name in docs

* Update TypeScript Compiler Options docs

* Update docs/plugin-transform-typescript.md

* Update docs/plugin-transform-typescript.md

Co-Authored-By: Brian Ng <bng412@gmail.com>

Co-authored-by: Brian Ng <bng412@gmail.com>
Co-authored-by: Nicolò Ribaudo <nicolo.ribaudo@gmail.com>

docs/plugin-transform-typescript.md

@@ -59,7 +59,7 @@ Because there are features of the TypeScript language which rely on the full typ
 
 1. This plugin does not support [`const enum`][const_enum]s because those require type information to compile.
 
-   **Workarounds**: 
+   **Workarounds**:
     - Use the plugin [babel-plugin-const-enum](https://www.npmjs.com/package/babel-plugin-const-enum).
     - Remove the `const`, which makes it available at runtime.
 
@@ -70,7 +70,7 @@ Because there are features of the TypeScript language which rely on the full typ
 1. Changes to your `tsconfig.json` are not reflected in babel. The build process will always behave as though [`isolatedModules`][iso-mods] is turned on, there are Babel-native alternative ways to set a lot of the [`tsconfig.json` options](#typescript-compiler-options) however.
 
 1. **Q**: Why doesn't Babel allow export of a `var` or `let`?
-  
+
    **A**: The TypeScript compiler dynamically changes how these variables are used depending on whether or not the value is mutated. Ultimately, this depends on a type-model and is outside the scope of Babel. A best-effort implementation would transform context-dependent usages of the variable to always use the `Namespace.Value` version instead of `Value`, in case it was mutated outside of the current file. Allowing `var` or `let` from Babel (as the transform is not-yet-written) is therefore is more likely than not to present itself as a bug when used as-if it was not `const`.
 
 
@@ -87,7 +87,7 @@ If you have existing code which uses the TypeScript-only [namespace][namespace]
 * `export`ing a variable using `var` or `let` in a `namespace` will result in an error: *"Namespaces exporting non-const are not supported by Babel. Change to const or ..."*
 
   **Workaround**: Use `const`. If some form of mutation is required, explicitly use an object with internal mutability.
-  
+
 * `namespace`s will not share their scope. In TypeScript, it is valid to refer to contextual items that a `namespace` extends without qualifying them, and the compiler will add the qualifier. In Babel, there is no type-model, and it is impossible to dynamically change references to match the established type of the parent object.
 
   Consider this code:
@@ -100,9 +100,9 @@ If you have existing code which uses the TypeScript-only [namespace][namespace]
     export const W = V;
   }
   ```
-  
+
   The TypeScript compiler compiles it to something like this:
-  
+
   ```javascript
   var N = {};
   (function (N) {
@@ -112,9 +112,9 @@ If you have existing code which uses the TypeScript-only [namespace][namespace]
     N.W = N.V;
   })(N);
   ```
-  
+
   While Babel will transform it to something like this:
-  
+
   ```javascript
   var N;
   (function (_N) {
@@ -124,7 +124,7 @@ If you have existing code which uses the TypeScript-only [namespace][namespace]
     const W = V;
   })(N || (N = {}));
   ```
-  
+
   As Babel doesn't understand the type of `N`, the reference to `V` will be `undefined` resulting in an error.
 
   **Workaround**: Explicitly refer to values not in the same namespace definition, even if they would be in the scope according to TypeScript. Examples:
@@ -153,19 +153,27 @@ If you have existing code which uses the TypeScript-only [namespace][namespace]
 
 `boolean`, defaults to `false`
 
+Forcibly enables `jsx` parsing. Otherwise angle brackets will be treated as TypeScript's legacy type assertion `var foo = <string>bar;`. Also, `isTSX: true` requires `allExtensions: true`.
+
 ### `jsxPragma`
 
 `string`, defaults to `React`
 
-Replace the function used when compiling JSX expressions.
-
-This is so that we know that the import is not a type import, and should not be removed
+Replace the function used when compiling JSX expressions. This is so that we know that the import is not a type import, and should not be removed.
 
 ### `allowNamespaces`
 
 `boolean`, defaults to `false` but will default to `true` in the [future](https://github.com/babel/notes/blob/master/2019/05/21.md#prs).
 
-> You can read more about configuring plugin options [here](https://babeljs.io/docs/en/plugins#plugin-options)
+Enables compilation of TypeScript namespaces.
+
+### `onlyRemoveTypeImports`
+
+`boolean`, defaults to `false`
+
+When set to `true`, the transform will only remove [type-only imports](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html#type-only-imports-exports) (introduced in TypeScript 3.8). This should only be used if you are using TypeScript >= 3.8.
+
+> You can read more about configuring plugin options [here](https://babeljs.io/docs/en/plugins#plugin-options).
 
 ## TypeScript Compiler Options
 
@@ -198,6 +206,8 @@ equivalents in Babel can be enabled by some configuration options or plugins.
   ```
 - `--importHelpers`
   This is the equivalent of the `@babel/plugin-transform-runtime` package.
+- `---importsNotUsedAsValues`
+  You can use the `onlyRemoveTypeImports` option to replicate this behavior. `onlyRemoveTypeImports: true` is equivalent to `importsNotUsedAsValues: preserve`, while `onlyRemoveTypeImports: false` is equivalent to `importsNotUsedAsValues: remove`. There is no equivalent for `importsNotUsedAsValues: error`.
 - `--inlineSourceMap`
   You can set the [`sourceMaps: "inline"`](https://babeljs.io/docs/en/options#sourcemaps) option in your `babel.config.json` file.
 - `--isolatedModules`

docs/preset-typescript.md

@@ -59,28 +59,32 @@ require("@babel/core").transform("code", {
 
 ### `isTSX`
 
-`boolean`, defaults to `false`.
+`boolean`, defaults to `false`
 
-Forcibly enables `jsx` parsing. Otherwise angle brackets will be treated as typescript's legacy type assertion `var foo = <string>bar;`. Also, `isTSX: true` requires `allExtensions: true`
+Forcibly enables `jsx` parsing. Otherwise angle brackets will be treated as typescript's legacy type assertion `var foo = <string>bar;`. Also, `isTSX: true` requires `allExtensions: true`.
 
 ### `jsxPragma`
 
-`string`, defaults to `React`.
+`string`, defaults to `React`
 
-Replace the function used when compiling JSX expressions.
-
-This is so that we know that the import is not a type import, and should not be removed
+Replace the function used when compiling JSX expressions. This is so that we know that the import is not a type import, and should not be removed.
 
 ### `allExtensions`
 
-`boolean`, defaults to `false`.
+`boolean`, defaults to `false`
 
-Indicates that every file should be parsed as TS or TSX (depending on the isTSX option)
+Indicates that every file should be parsed as TS or TSX (depending on the `isTSX` option).
 
 ### `allowNamespaces`
 
 `boolean`, uses the default set by [`@babel/plugin-transform-typescript`](https://babeljs.io/docs/en/babel-plugin-transform-typescript#allownamespaces).
 
 Enables compilation of TypeScript namespaces.
 
-> You can read more about configuring preset options [here](https://babeljs.io/docs/en/presets#preset-options)
+### `onlyRemoveTypeImports`
+
+`boolean`, defaults to `false`
+
+When set to `true`, the transform will only remove [type-only imports](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html#type-only-imports-exports) (introduced in TypeScript 3.8). This should only be used if you are using TypeScript >= 3.8.
+
+> You can read more about configuring preset options [here](https://babeljs.io/docs/en/presets#preset-options).

website/versioned_docs/version-7.0.0/plugin-transform-typescript.md

@@ -74,13 +74,13 @@ require("@babel/core").transform("code", {
 
 `boolean`, defaults to `false`
 
+Forcibly enables `jsx` parsing. Otherwise angle brackets will be treated as typescript's legacy type assertion `var foo = <string>bar;`. Also, `isTSX: true` requires `allExtensions: true`.
+
 ### `jsxPragma`
 
 `string`, defaults to `React`
 
-Replace the function used when compiling JSX expressions.
-
-This is so that we know that the import is not a type import, and should not be removed
+Replace the function used when compiling JSX expressions. This is so that we know that the import is not a type import, and should not be removed.
 
 > You can read more about configuring plugin options [here](https://babeljs.io/docs/en/plugins#plugin-options)
 
@@ -156,5 +156,3 @@ using different configuration options or plugins.
 [exin]: https://www.typescriptlang.org/docs/handbook/modules.html#export--and-import--require
 [fm]: https://github.com/Microsoft/dtslint/blob/master/docs/no-single-declare-module.md
 [tsc-options]: https://www.typescriptlang.org/docs/handbook/compiler-options.html
-
-

website/versioned_docs/version-7.0.0/preset-typescript.md

@@ -59,22 +59,20 @@ require("@babel/core").transform("code", {
 
 ### `isTSX`
 
-`boolean`, defaults to `false`.
+`boolean`, defaults to `false`
 
-Forcibly enables `jsx` parsing. Otherwise angle brackets will be treated as typescript's legacy type assertion `var foo = <string>bar;`. Also, `isTSX: true` requires `allExtensions: true`
+Forcibly enables `jsx` parsing. Otherwise angle brackets will be treated as typescript's legacy type assertion `var foo = <string>bar;`. Also, `isTSX: true` requires `allExtensions: true`.
 
 ### `jsxPragma`
 
-`string`, defaults to `React`.
+`string`, defaults to `React`
 
-Replace the function used when compiling JSX expressions.
-
-This is so that we know that the import is not a type import, and should not be removed
+Replace the function used when compiling JSX expressions. This is so that we know that the import is not a type import, and should not be removed.
 
 ### `allExtensions`
 
-`boolean`, defaults to `false`.
+`boolean`, defaults to `false`
 
-Indicates that every file should be parsed as TS or TSX (depending on the isTSX option)
+Indicates that every file should be parsed as TS or TSX (depending on the `isTSX` option).
 
 > You can read more about configuring preset options [here](https://babeljs.io/docs/en/presets#preset-options)

website/versioned_docs/version-7.5.0/plugin-transform-typescript.md

@@ -154,18 +154,20 @@ If you have existing code which uses the TypeScript-only [namespace][namespace]
 
 `boolean`, defaults to `false`
 
+Forcibly enables `jsx` parsing. Otherwise angle brackets will be treated as typescript's legacy type assertion `var foo = <string>bar;`. Also, `isTSX: true` requires `allExtensions: true`.
+
 ### `jsxPragma`
 
 `string`, defaults to `React`
 
-Replace the function used when compiling JSX expressions.
-
-This is so that we know that the import is not a type import, and should not be removed
+Replace the function used when compiling JSX expressions. This is so that we know that the import is not a type import, and should not be removed.
 
 ### `allowNamespaces`
 
 `boolean`, defaults to `false` but will default to `true` in the [future](https://github.com/babel/notes/blob/master/2019/05/21.md#prs).
 
+Enables compilation of TypeScript namespaces.
+
 > You can read more about configuring plugin options [here](https://babeljs.io/docs/en/plugins#plugin-options)
 
 ## TypeScript Compiler Options

website/versioned_docs/version-7.6.0/preset-typescript.md

@@ -59,23 +59,21 @@ require("@babel/core").transform("code", {
 
 ### `isTSX`
 
-`boolean`, defaults to `false`.
+`boolean`, defaults to `false`
 
-Forcibly enables `jsx` parsing. Otherwise angle brackets will be treated as typescript's legacy type assertion `var foo = <string>bar;`. Also, `isTSX: true` requires `allExtensions: true`
+Forcibly enables `jsx` parsing. Otherwise angle brackets will be treated as typescript's legacy type assertion `var foo = <string>bar;`. Also, `isTSX: true` requires `allExtensions: true`.
 
 ### `jsxPragma`
 
-`string`, defaults to `React`.
+`string`, defaults to `React`
 
-Replace the function used when compiling JSX expressions.
-
-This is so that we know that the import is not a type import, and should not be removed
+Replace the function used when compiling JSX expressions. This is so that we know that the import is not a type import, and should not be removed.
 
 ### `allExtensions`
 
-`boolean`, defaults to `false`.
+`boolean`, defaults to `false`
 
-Indicates that every file should be parsed as TS or TSX (depending on the isTSX option)
+Indicates that every file should be parsed as TS or TSX (depending on the `isTSX` option).
 
 ### `allowNamespaces`
 

website/versioned_docs/version-7.7.0/plugin-transform-typescript.md

@@ -154,18 +154,20 @@ If you have existing code which uses the TypeScript-only [namespace][namespace]
 
 `boolean`, defaults to `false`
 
+Forcibly enables `jsx` parsing. Otherwise angle brackets will be treated as typescript's legacy type assertion `var foo = <string>bar;`. Also, `isTSX: true` requires `allExtensions: true`.
+
 ### `jsxPragma`
 
 `string`, defaults to `React`
 
-Replace the function used when compiling JSX expressions.
-
-This is so that we know that the import is not a type import, and should not be removed
+Replace the function used when compiling JSX expressions. This is so that we know that the import is not a type import, and should not be removed.
 
 ### `allowNamespaces`
 
 `boolean`, defaults to `false` but will default to `true` in the [future](https://github.com/babel/notes/blob/master/2019/05/21.md#prs).
 
+Enables compilation of TypeScript namespaces.
+
 > You can read more about configuring plugin options [here](https://babeljs.io/docs/en/plugins#plugin-options)
 
 ## TypeScript Compiler Options

website/versioned_docs/version-7.8.0/plugin-transform-typescript.md

@@ -154,18 +154,20 @@ If you have existing code which uses the TypeScript-only [namespace][namespace]
 
 `boolean`, defaults to `false`
 
+Forcibly enables `jsx` parsing. Otherwise angle brackets will be treated as typescript's legacy type assertion `var foo = <string>bar;`. Also, `isTSX: true` requires `allExtensions: true`.
+
 ### `jsxPragma`
 
 `string`, defaults to `React`
 
-Replace the function used when compiling JSX expressions.
-
-This is so that we know that the import is not a type import, and should not be removed
+Replace the function used when compiling JSX expressions. This is so that we know that the import is not a type import, and should not be removed.
 
 ### `allowNamespaces`
 
 `boolean`, defaults to `false` but will default to `true` in the [future](https://github.com/babel/notes/blob/master/2019/05/21.md#prs).
 
+Enables compilation of TypeScript namespaces.
+
 > You can read more about configuring plugin options [here](https://babeljs.io/docs/en/plugins#plugin-options)
 
 ## TypeScript Compiler Options

website/versioned_docs/version-7.8.0/preset-typescript.md

@@ -60,23 +60,21 @@ require("@babel/core").transform("code", {
 
 ### `isTSX`
 
-`boolean`, defaults to `false`.
+`boolean`, defaults to `false`
 
-Forcibly enables `jsx` parsing. Otherwise angle brackets will be treated as typescript's legacy type assertion `var foo = <string>bar;`. Also, `isTSX: true` requires `allExtensions: true`
+Forcibly enables `jsx` parsing. Otherwise angle brackets will be treated as typescript's legacy type assertion `var foo = <string>bar;`. Also, `isTSX: true` requires `allExtensions: true`.
 
 ### `jsxPragma`
 
-`string`, defaults to `React`.
+`string`, defaults to `React`
 
-Replace the function used when compiling JSX expressions.
-
-This is so that we know that the import is not a type import, and should not be removed
+Replace the function used when compiling JSX expressions. This is so that we know that the import is not a type import, and should not be removed.
 
 ### `allExtensions`
 
-`boolean`, defaults to `false`.
+`boolean`, defaults to `false`
 
-Indicates that every file should be parsed as TS or TSX (depending on the isTSX option)
+Indicates that every file should be parsed as TS or TSX (depending on the `isTSX` option).
 
 ### `allowNamespaces`