From 85dd6de4701fbc516868b8599fca8a95461f3281 Mon Sep 17 00:00:00 2001
From: Andrew Bradley <cspotcode@gmail.com>
Date: Fri, 9 Jul 2021 16:29:47 -0400
Subject: [PATCH] rebuild the readme

---
 README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/README.md b/README.md
index 1015d6be0..41e98f958 100644
--- a/README.md
+++ b/README.md
@@ -72,6 +72,8 @@ Native ESM support is currently experimental. For usage, limitations, and to pro
     *   [Third-party transpilers](#third-party-transpilers)
         *   [Bundled `swc` integration](#bundled-swc-integration)
         *   [Writing your own integration](#writing-your-own-integration)
+    *   [Module type overrides](#module-type-overrides)
+        *   [Caveats](#caveats)
 *   [Recipes](#recipes)
     *   [Watching and Restarting](#watching-and-restarting)
     *   [AVA](#ava)
@@ -321,6 +323,9 @@ node --trace-deprecation --abort-on-uncaught-exception -r ts-node/register ./ind
 *   `-r, --require [path]`   Require a node module before execution
 *   `--cwd`   Behave as if invoked in this working directory <br/>*Default:* `process.cwd()`<br/>*Environment:* `TS_NODE_CWD`
 *   `--emit`   Emit output files into `.ts-node` directory <br/>*Default:* `false` <br/>*Environment:* `TS_NODE_EMIT`
+*   `--scope`  Scope compiler to files within `scopeDir`.  Anything outside this directory is ignored. <br/>\*Default: `false` <br/>*Environment:* `TS_NODE_SCOPE`
+*   `--scopeDir` Directory within which compiler is limited when `scope` is enabled. <br/>*Default:* First of: `tsconfig.json` "rootDir" if specified, directory containing `tsconfig.json`, or cwd if no `tsconfig.json` is loaded.<br/>*Environment:* `TS_NODE_SCOPE_DIR`
+*   `moduleType`  Override the module type of certain files, ignoring the `package.json` `"type"` field.  See [Module type overrides](#module-type-overrides) for details.<br/>*Default:* obeys `package.json` `"type"` and `tsconfig.json` `"module"` <br/>*Can only be specified via `tsconfig.json` or API.*
 *   `TS_NODE_HISTORY` Path to history file for REPL <br/>*Default:* `~/.ts_node_repl_history`<br/>
 
 ## API
@@ -671,6 +676,53 @@ To write your own transpiler integration, check our [API docs](https://typestron
 Integrations are `require()`d, so they can be published to npm.  The module must export a `create` function matching the
 [`TranspilerModule`](https://typestrong.org/ts-node/api/interfaces/TranspilerModule.html) interface.
 
+## Module type overrides
+
+When deciding between CommonJS and native ECMAScript modules, `ts-node` defaults to matching vanilla `node` and `tsc`
+behavior.  This means TypeScript files are transformed according to your `tsconfig.json` `"module"` option and executed
+according to node's rules for the `package.json` `"type"` field.
+
+In some projects you may need to override this behavior for some files.  For example, in a webpack
+project, you may have `package.json` configured with `"type": "module"` and `tsconfig.json` with
+`"module": "esnext"`.  However, webpack uses our CommonJS hook to execute your `webpack.config.ts`,
+so you need to force your webpack config and any supporting scripts to execute as CommonJS.
+
+In these situations, our `moduleTypes` option lets you override certain files, forcing execution as
+CommonJS or ESM.  Node supports similar overriding via `.cjs` and `.mjs` file extensions, but `.ts` files cannot use them.
+`moduleTypes` achieves the same effect, and *also* overrides your `tsconfig.json` `"module"` config appropriately.
+
+The following example tells `ts-node` to execute a webpack config as CommonJS:
+
+```jsonc title=tsconfig.json
+{
+  "ts-node": {
+    "transpileOnly": true,
+    "moduleTypes": {
+      "webpack.config.ts": "cjs",
+      // Globs are also supported with the same behavior as tsconfig "include"
+      "webpack-config-scripts/**/*": "cjs"
+    }
+  },
+  "compilerOptions": {
+    "module": "es2020",
+    "target": "es2020"
+  }
+}
+```
+
+Each key is a glob pattern with the same syntax as tsconfig's `"include"` array.
+When multiple patterns match the same file, the last pattern takes precedence.
+
+*   `cjs` overrides matches files to compile and execute as CommonJS.
+*   `esm` overrides matches files to compile and execute as native ECMAScript modules.
+*   `package` resets either of the above to default behavior, which obeys `package.json` `"type"` and `tsconfig.json` `"module"` options.
+
+### Caveats
+
+Files with an overridden module type are transformed with the same limitations as [`isolatedModules`](https://www.typescriptlang.org/tsconfig#isolatedModules).  This will only affect rare cases such as using `const enum`s with [`preserveConstEnums`](https://www.typescriptlang.org/tsconfig#preserveConstEnums) disabled.
+
+This feature is meant to faciliate scenarios where normal `compilerOptions` and `package.json` configuration is not possible.  For example, a `webpack.config.ts` cannot be given its own `package.json` to override `"type"`.  Wherever possible you should favor using traditional `package.json` and `tsconfig.json` configurations.
+
 # Recipes
 
 ## Watching and Restarting