From 093209fe7078d09031600224811e228becabcca5 Mon Sep 17 00:00:00 2001
From: Houston Agent <houston@base44.local>
Date: Tue, 5 May 2026 12:35:23 +0000
Subject: [PATCH] docs(custom-webpack): document ts-node configuration for
 custom tsconfig (fixes #1162)

---
 packages/custom-webpack/README.md | 41 +++++++++++++++++++++++++++++--
 1 file changed, 39 insertions(+), 2 deletions(-)

diff --git a/packages/custom-webpack/README.md b/packages/custom-webpack/README.md
index 16af93d76..ce9186156 100644
--- a/packages/custom-webpack/README.md
+++ b/packages/custom-webpack/README.md
@@ -21,6 +21,7 @@ Allow customizing build configuration without ejecting webpack configuration (`n
   - [Custom Webpack Promisified Config](#custom-webpack-promisified-config)
   - [Custom Webpack Config Function](#custom-webpack-config-function)
 - [Index Transform](#index-transform)
+  - [Using a Custom TypeScript Configuration for indexTransform](#using-a-custom-typescript-configuration-for-indextransform)
   - [Example](#example-2)
 - [ES Modules (ESM) Support](#es-modules-esm-support)
 - [Verbose Logging](#verbose-logging)
@@ -30,7 +31,6 @@ Allow customizing build configuration without ejecting webpack configuration (`n
 
 > ⚠️ **Version alignment:** The major version of `@angular-builders/custom-webpack` must match the major version of `@angular/core` in your project. For example, Angular 19 requires `@angular-builders/custom-webpack@19.x`, Angular 20 requires `@angular-builders/custom-webpack@20.x`, etc. Using a mismatched version is the most common source of issues.
 
-
 ## Previous versions
 
 <details>
@@ -416,7 +416,6 @@ You can check out an example for plugins merge in the [unit tests](./src/webpack
 >
 > For full control over the merge, use a [function export](#custom-webpack-config-function) — you receive the full base config and return a new one, bypassing automatic merge entirely.
 
-
 ## Custom Webpack Promisified Config
 
 Webpack config can also export a `Promise` object that resolves custom config. Given the following example:
@@ -582,6 +581,44 @@ In the example we add a paragraph with build configuration to your `index.html`.
 
 Full example [here](../../examples/custom-webpack/full-cycle-app).
 
+### Using a Custom TypeScript Configuration for indexTransform
+
+If your `indexTransform` file requires a different TypeScript configuration than the default `tsConfig` from the build target, you can specify it using the `ts-node` section in your `tsconfig.json`.
+
+For example, if you want your `indexTransform.ts` to use a different `tsconfig` file:
+
+`tsconfig.json`:
+```json
+{
+  "compilerOptions": {
+    ...
+  },
+  "ts-node": {
+    "compilerOptions": {
+      "module": "commonjs"
+    }
+  }
+}
+```
+
+Or, to use an entirely different `tsconfig` file for `ts-node`:
+
+`tsconfig.json`:
+```json
+{
+  "compilerOptions": {
+    ...
+  },
+  "ts-node": {
+    "tsconfig": "./tsconfig.ts-node.json"
+  }
+}
+```
+
+This is useful when your `indexTransform` has different transpilation requirements than the main build (e.g., different module format, different target, or different lib configuration). For more details on `ts-node` configuration options, see the [ts-node documentation](https://typestrong.org/ts-node/docs/configuration/#via-tsconfigjson-recommended).
+
+The same approach applies to `customWebpackConfig` if it's written in TypeScript.
+
 # ES Modules (ESM) Support
 
 Custom Webpack builder fully supports ESM.