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
*Default:* `process.cwd()`
*Environment:* `TS_NODE_CWD`
* `--emit` Emit output files into `.ts-node` directory
*Default:* `false`
*Environment:* `TS_NODE_EMIT`
+* `--scope` Scope compiler to files within `scopeDir`. Anything outside this directory is ignored.
\*Default: `false`
*Environment:* `TS_NODE_SCOPE`
+* `--scopeDir` Directory within which compiler is limited when `scope` is enabled.
*Default:* First of: `tsconfig.json` "rootDir" if specified, directory containing `tsconfig.json`, or cwd if no `tsconfig.json` is loaded.
*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.
*Default:* obeys `package.json` `"type"` and `tsconfig.json` `"module"`
*Can only be specified via `tsconfig.json` or API.*
* `TS_NODE_HISTORY` Path to history file for REPL
*Default:* `~/.ts_node_repl_history`
## 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