nx 23.0.0-beta.2 → 23.0.0-beta.21

package/dist/src/plugins/js/utils/register.js

@@ -1,9 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.forceRegisterEsmLoader = forceRegisterEsmLoader;
+exports.isNativeStripPreferred = isNativeStripPreferred;
 exports.registerTsProject = registerTsProject;
 exports.getSwcTranspiler = getSwcTranspiler;
 exports.getTsNodeTranspiler = getTsNodeTranspiler;
 exports.getTranspiler = getTranspiler;
+exports.isNativeTypeStripError = isNativeTypeStripError;
+exports.isCjsSyntaxError = isCjsSyntaxError;
+exports.isRequireInEsmScopeError = isRequireInEsmScopeError;
+exports.isTsEsmSyntaxError = isTsEsmSyntaxError;
+exports.isTsEsmNamedExportLinkageError = isTsEsmNamedExportLinkageError;
+exports.loadTsFile = loadTsFile;
+exports.requireWithTsconfigFallback = requireWithTsconfigFallback;
 exports.registerTranspiler = registerTranspiler;
 exports.registerTsConfigPaths = registerTsConfigPaths;
 exports.getTsNodeCompilerOptions = getTsNodeCompilerOptions;
@@ -16,6 +25,74 @@ const swcNodeInstalled = packageIsInstalled('@swc-node/register');
 const tsNodeInstalled = packageIsInstalled('ts-node/register');
 let ts;
 let isTsEsmLoaderRegistered = false;
+/**
+ * Force-register an ESM loader (`@swc-node/register/esm` if available, else
+ * `ts-node/esm`) via `Module.register` so dynamic `import()` of TS files
+ * goes through a transpiler.
+ *
+ * **IMPORTANT — global side effect:** `Module.register` is one-shot per
+ * process and applies to *every* subsequent ESM resolution in the process.
+ * Calling this trades native Node.js TypeScript stripping for transpiled
+ * loading on the dynamic-import path for the rest of the run. CJS
+ * `require()` is unaffected (different hook), so `.cts` files via require
+ * keep using native strip + swc-node's `Module._extensions` hook.
+ *
+ * Required for the niche case where an ESM config (`.mts` or `.ts` resolved
+ * as ESM) combines top-level await with TypeScript syntax that native strip
+ * can't handle (`enum`, runtime `namespace`, etc.). TLA forces dynamic
+ * `import()`, which bypasses the CJS hook chain - the only way to intercept
+ * is `Module.register`.
+ *
+ * Idempotent: subsequent calls are no-ops.
+ *
+ * Throws if neither `@swc-node/register` nor `ts-node` is installed.
+ */
+function forceRegisterEsmLoader() {
+    ensureEsmLoaderRegistered({ required: true });
+}
+function ensureEsmLoaderRegistered(opts) {
+    if (isTsEsmLoaderRegistered)
+        return;
+    const module = require('node:module');
+    if (typeof module.register !== 'function') {
+        if (opts.required) {
+            throw new Error(`${logger_1.NX_PREFIX} Module.register is not available in this Node.js version - cannot register an ESM loader for the TypeScript fallback. ${STRIP_TYPES_OPT_OUT_HINT}`);
+        }
+        return;
+    }
+    // ts-node reads compilerOptions from this env var. Setting nodenext
+    // module/resolution avoids surprises when ts-node is the chosen loader.
+    process.env.TS_NODE_COMPILER_OPTIONS ??= JSON.stringify({
+        moduleResolution: 'nodenext',
+        module: 'nodenext',
+    });
+    // Prefer @swc-node/register/esm (faster) over ts-node/esm.
+    const swcEsm = tryResolveLoader('@swc-node/register/esm');
+    const tsNodeEsm = tryResolveLoader('ts-node/esm');
+    const loaderPath = swcEsm ?? tsNodeEsm;
+    if (!loaderPath) {
+        if (opts.required) {
+            throw new Error(`${logger_1.NX_PREFIX} Cannot register an ESM TypeScript loader to fall back from native stripping. Install @swc-node/register or ts-node, or ${STRIP_TYPES_OPT_OUT_HINT}`);
+        }
+        isTsEsmLoaderRegistered = true;
+        return;
+    }
+    if (process.env.NX_VERBOSE_LOGGING === 'true') {
+        const loaderName = swcEsm ? '@swc-node/register/esm' : 'ts-node/esm';
+        logger_1.logger.warn((0, logger_1.stripIndent)(`${logger_1.NX_PREFIX} Registering ESM TypeScript loader ${loaderName}. All subsequent ESM imports in this process will go through it - native Node.js TypeScript stripping is forfeited for the dynamic-import path.`));
+    }
+    const url = require('node:url');
+    module.register(url.pathToFileURL(loaderPath));
+    isTsEsmLoaderRegistered = true;
+}
+function tryResolveLoader(specifier) {
+    try {
+        return require.resolve(specifier);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * tsx is a utility to run TypeScript files in node which is growing in popularity:
  * https://tsx.is
@@ -51,65 +128,72 @@ const isInvokedByTsx = (() => {
         importArgs.some((a) => isTsxPath(a)));
 })();
 /**
- * Whether the current Node.js version supports native TypeScript execution
- * via type stripping (Node 22.6+).
+ * Whether the current Node.js runtime exposes native TypeScript type
+ * stripping. This is the authoritative gate - it correctly handles every
+ * way Node ships TS support:
+ *   - Node 23.6+: unflagged, on by default
+ *   - Node 22.18+ LTS: backported unflagged
+ *   - Node 22.6-22.17 + `--experimental-strip-types` (or `--experimental-transform-types`)
  *
- * process.features.typescript is 'strip' | 'transform' | false in Node 22.6+
+ * `process.features.typescript` is `'strip' | 'transform' | false`.
  */
 const nodeSupportsNativeTypescript = !!process.features
     ?.typescript;
 /**
- * When process.features.typescript is truthy and the user has opted in via
- * NX_PREFER_NODE_STRIP_TYPES=true, we can skip registering swc-node or ts-node
- * transpilers since Node.js will handle TypeScript natively.
+ * When process.features.typescript is truthy, default to letting Node.js
+ * handle TypeScript natively via type stripping and skip registering swc-node
+ * or ts-node. Users can opt out by setting NX_PREFER_NODE_STRIP_TYPES=false.
  *
- * This can significantly improve performance when loading TypeScript config files, but there are some things
- * that won't work. See: https://nodejs.org/api/typescript.html#full-typescript-support
+ * Some constructs (enum, runtime namespace, legacy decorators,
+ * import = require, parameter properties, etc.) aren't supported by native
+ * type stripping. `loadTsFile` catches these failures and falls back to
+ * registering swc/ts-node + tsconfig-paths automatically.
  *
- * TODO(v23): We should turn this on by default, but look at if need to fallback to SWC/ts-node if it fails.
+ * See: https://nodejs.org/api/typescript.html#full-typescript-support
  */
 const preferNodeStripTypes = (() => {
-    if (process.env.NX_PREFER_NODE_STRIP_TYPES !== 'true') {
+    if (!nodeSupportsNativeTypescript) {
         return false;
     }
-    return nodeSupportsNativeTypescript;
+    return process.env.NX_PREFER_NODE_STRIP_TYPES !== 'false';
 })();
-function registerTsProject(path, configFilename) {
+/**
+ * Skip tsconfig-paths registration on the swc/ts-node fallback path. Useful
+ * for workspaces relying on package manager workspaces (pnpm, yarn, npm) for
+ * project linking, where tsconfig path aliases aren't needed.
+ */
+const disableTsConfigPaths = process.env.NX_DISABLE_TSCONFIG_PATHS === 'true';
+/**
+ * Whether Nx will defer to Node's native TypeScript stripping for the next
+ * `.ts` load. Mirrors the gate used by `loadTsFile`/`registerTsProject` so
+ * other registration sites (e.g. plugin transpiler) can stay aligned.
+ */
+function isNativeStripPreferred() {
+    return preferNodeStripTypes;
+}
+/**
+ * This function registers either ts-node or swc-node to transpile TypeScript files on the fly.
+ * It also registers tsconfig-paths to handle path mapping based on the provided tsconfig.
+ *
+ * The TypeScript transpiler registration is done regardless of NX_PREFER_NODE_STRIP_TYPES.
+ * If you want to skip transpiler registration, it is recommended that you check `process.features.typescript`.
+ *
+ * @returns cleanup function
+ */
+function registerTsProject(tsConfigPath) {
     // See explanation alongside isInvokedByTsx declaration
     if (isInvokedByTsx) {
         return () => { };
     }
-    const tsConfigPath = configFilename ? (0, path_1.join)(path, configFilename) : path;
-    // See explanation alongside preferNodeStripTypes declaration
-    // When using Node.js native type stripping, skip transpiler registration
-    // but still register tsconfig-paths for path mapping support
-    if (preferNodeStripTypes) {
-        return registerTsConfigPaths(tsConfigPath);
-    }
     const { compilerOptions, tsConfigRaw } = readCompilerOptions(tsConfigPath);
     const cleanupFunctions = [
         registerTsConfigPaths(tsConfigPath),
         registerTranspiler(compilerOptions, tsConfigRaw),
     ];
-    // Add ESM support for `.ts` files.
-    // NOTE: There is no cleanup function for this, as it's not possible to unregister the loader.
-    //       Based on limited testing, it doesn't seem to matter if we register it multiple times, but just in
-    //       case let's keep a flag to prevent it.
-    if (!isTsEsmLoaderRegistered) {
-        // We need a way to ensure that `.ts` files are treated as ESM not CJS.
-        // Since there is no way to pass compilerOptions like we do with the programmatic API, we should default
-        // the environment variable that ts-node checks.
-        process.env.TS_NODE_COMPILER_OPTIONS ??= JSON.stringify({
-            moduleResolution: 'nodenext',
-            module: 'nodenext',
-        });
-        const module = require('node:module');
-        if (module.register && packageIsInstalled('ts-node/esm')) {
-            const url = require('node:url');
-            module.register(url.pathToFileURL(require.resolve('ts-node/esm')));
-        }
-        isTsEsmLoaderRegistered = true;
-    }
+    // Best-effort ESM loader registration so dynamic import() of .ts/.mts
+    // files goes through a transpiler. No-op if no ESM loader package is
+    // installed.
+    ensureEsmLoaderRegistered({ required: false });
     return () => {
         for (const fn of cleanupFunctions) {
             fn();
@@ -253,6 +337,307 @@ function getTranspiler(compilerOptions, tsConfigRaw) {
         return currRegistrationEntry.cleanup;
     }
 }
+/**
+ * Node.js throws this code when native type stripping hits an unsupported
+ * construct (enum, runtime namespace, legacy decorators, import = require,
+ * parameter properties on older Node, etc.).
+ *
+ * Exported for tests.
+ */
+function isNativeTypeStripError(err) {
+    if (!err || typeof err !== 'object')
+        return false;
+    return (err.code === 'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX');
+}
+/**
+ * Module resolution failures - typically a tsconfig path alias that hasn't
+ * been registered yet, or a workspace lib not surfaced via package manager
+ * symlinks. CJS uses `MODULE_NOT_FOUND`, ESM uses `ERR_MODULE_NOT_FOUND`.
+ */
+function isModuleNotFoundError(err) {
+    if (!err || typeof err !== 'object')
+        return false;
+    const code = err.code;
+    return code === 'MODULE_NOT_FOUND' || code === 'ERR_MODULE_NOT_FOUND';
+}
+/**
+ * A SyntaxError thrown while parsing a forced-CJS file (`.cts`/`.cjs`) as
+ * CommonJS - typically ESM syntax in a CJS file (e.g. `export default` in
+ * `.cts`). Pre-v23 this worked because swc-node's CJS hook compiled away the
+ * ESM syntax; under native strip swc-node isn't registered, so the file
+ * reaches Node's strict CJS parser. swc-node tolerates ESM syntax in `.cts`
+ * (`register()` forces `module: commonjs` regardless of extension), so
+ * escalating to the swc/ts-node fallback recovers the legacy behavior.
+ */
+function isCjsSyntaxError(err, filePath) {
+    if (!(err instanceof SyntaxError))
+        return false;
+    return filePath.endsWith('.cts') || filePath.endsWith('.cjs');
+}
+/**
+ * A ReferenceError from Node treating a `.ts`/`.mts` file as ESM and the file
+ * relying on a CJS-only global: `require`, `__dirname`, or `__filename`.
+ * Pre-v23 swc-node compiled `.ts` to CJS where these globals exist; under
+ * native strip Node detects ESM via `import`/`export` syntax and these globals
+ * are undefined. Registering swc/ts-node compiles ESM->CJS and restores the
+ * legacy globals.
+ */
+function isRequireInEsmScopeError(err, filePath) {
+    if (!(err instanceof ReferenceError))
+        return false;
+    if (!(filePath.endsWith('.ts') || filePath.endsWith('.mts')))
+        return false;
+    // Node's exact phrasing varies across versions / strip modes. Match the
+    // bare-name form too (e.g. `__dirname is not defined`) so the fallback
+    // still triggers when the trailing "in ES module scope" is absent.
+    const msg = err.message;
+    return /(require|__dirname|__filename) is not defined/.test(msg);
+}
+function isTsEsmSyntaxError(err, filePath) {
+    if (!(err instanceof SyntaxError))
+        return false;
+    if (!filePath.endsWith('.ts'))
+        return false;
+    // Node has multiple phrasings for ESM-in-CJS-scope syntax errors depending
+    // on whether the offending token is `import` or `export` and which parser
+    // path triggered: "Cannot use import statement outside a module" or
+    // "Unexpected token 'export'" / "Unexpected token 'import'". swc-node's
+    // CJS hook compiles ESM->CJS regardless of the surface error, so all of
+    // these should escalate to the same fallback.
+    const msg = err.message;
+    return (msg.includes('Cannot use import statement outside a module') ||
+        /Unexpected token ['"](export|import)['"]/.test(msg));
+}
+function isTsEsmNamedExportLinkageError(err, filePath) {
+    if (!(err instanceof SyntaxError))
+        return false;
+    return ((filePath.endsWith('.ts') || filePath.endsWith('.mts')) &&
+        err.message.includes('does not provide an export named'));
+}
+/**
+ * Hint appended to errors that the lazy fallback couldn't recover from.
+ * Points users at the env opt-out for cases native strip can't reach (e.g.
+ * ESM with top-level await + unsupported TS syntax, where swc-node's CJS
+ * Module._extensions hook can't intercept dynamic `import()`).
+ */
+const NX_PREFER_NODE_STRIP_TYPES_DOCS_URL = 'https://nx.dev/docs/reference/environment-variables#nx-prefer-node-strip-types';
+const STRIP_TYPES_OPT_OUT_HINT = `Set NX_PREFER_NODE_STRIP_TYPES=false to opt out of Node's native TypeScript stripping and use swc/ts-node instead. See ${NX_PREFER_NODE_STRIP_TYPES_DOCS_URL}`;
+/**
+ * Load a TypeScript file via `require()`.
+ *
+ * When the runtime exposes native TypeScript stripping
+ * (`process.features.typescript`) and the user hasn't opted out via
+ * `NX_PREFER_NODE_STRIP_TYPES=false`, the file loads directly with no
+ * swc/ts-node and no tsconfig-paths registration. If Node throws on an
+ * unsupported construct (enum, runtime namespace, legacy decorators, etc.),
+ * this registers swc/ts-node + tsconfig-paths and retries - matching the
+ * pre-v23 registration. Set `NX_DISABLE_TSCONFIG_PATHS=true` to skip
+ * tsconfig-paths even on fallback (useful when relying on package manager
+ * workspaces). Set `NX_VERBOSE_LOGGING=true` to log when fallback triggers.
+ *
+ * When native strip is opted out (`NX_PREFER_NODE_STRIP_TYPES=false` or
+ * unsupported Node), uses the legacy `registerTsProject` path.
+ *
+ * `tsConfigPath` is only consulted on the swc/ts-node fallback path (for
+ * compilerOptions) and for tsconfig-paths registration. Native strip ignores
+ * it. When omitted, defaults to the workspace root tsconfig.
+ *
+ * Note on ESM: Node 22.12+ supports `require()` of synchronous ESM by default,
+ * so most ESM `.ts` configs load via this function without issue. Modules
+ * that use top-level await throw `ERR_REQUIRE_ASYNC_MODULE` and must be
+ * loaded with dynamic `import()` instead. `ERR_REQUIRE_ESM` (legacy code)
+ * bubbles unchanged for the rare case it still fires, so async-aware callers
+ * can dispatch to `import()`.
+ *
+ * @returns the loaded module
+ */
+function loadTsFile(filePath, tsConfigPath) {
+    const resolvedTsConfigPath = tsConfigPath ?? (0, typescript_1.getRootTsConfigPath)();
+    if (isInvokedByTsx) {
+        return require(filePath);
+    }
+    if (!preferNodeStripTypes) {
+        if (!resolvedTsConfigPath) {
+            throw new Error(`${logger_1.NX_PREFIX} loadTsFile could not find a workspace tsconfig while loading ${filePath} on the swc/ts-node path. Pass an explicit tsConfigPath or add a tsconfig.base.json/tsconfig.json at the workspace root.`);
+        }
+        const cleanup = registerTsProject(resolvedTsConfigPath);
+        try {
+            return require(filePath);
+        }
+        finally {
+            cleanup();
+        }
+    }
+    // Native strip path: no registration up front. pnpm/npm/yarn workspaces
+    // resolve aliases without tsconfig-paths. On failure, lazy-register what
+    // the specific error code indicates is needed and retry:
+    //   - MODULE_NOT_FOUND -> first try tsconfig-paths (alias resolution).
+    //     If that still fails (e.g. extensionless `import './foo'` when
+    //     `foo.ts` is adjacent - Node's resolver doesn't add `.ts`), escalate
+    //     to swc/ts-node which handles `.ts` extension resolution.
+    //   - ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX -> register swc/ts-node + tsconfig-paths
+    // Each registration kind runs at most once, so a file recovers in at
+    // most three attempts.
+    let pathsRegistered = false;
+    let transpilerRegistered = false;
+    const cleanups = [];
+    const registerTranspilerFallback = (err) => {
+        if (!swcNodeInstalled && !tsNodeInstalled) {
+            const original = err instanceof Error ? err.message : String(err);
+            throw new Error(`${logger_1.NX_PREFIX} ${filePath} could not be loaded under Node's native TypeScript stripping (${original}). Install @swc-node/register and @swc/core (or ts-node) to enable the swc/ts-node fallback, or ${STRIP_TYPES_OPT_OUT_HINT}`);
+        }
+        if (!resolvedTsConfigPath) {
+            throw new Error(`${logger_1.NX_PREFIX} ${filePath} requires the swc/ts-node fallback but no workspace tsconfig was found. Pass an explicit tsConfigPath or add a tsconfig.base.json/tsconfig.json at the workspace root. ${STRIP_TYPES_OPT_OUT_HINT}`);
+        }
+        if (!pathsRegistered && !disableTsConfigPaths) {
+            cleanups.push(registerTsConfigPaths(resolvedTsConfigPath));
+            pathsRegistered = true;
+        }
+        const { compilerOptions, tsConfigRaw } = readCompilerOptions(resolvedTsConfigPath);
+        cleanups.push(registerTranspiler(compilerOptions, tsConfigRaw));
+        transpilerRegistered = true;
+    };
+    try {
+        for (let attempt = 1;; attempt++) {
+            try {
+                if (attempt > 1) {
+                    try {
+                        delete require.cache[require.resolve(filePath)];
+                    }
+                    catch {
+                        // require.resolve may throw if the failed load never reached cache
+                    }
+                }
+                return require(filePath);
+            }
+            catch (err) {
+                // Cheap fallback first: register tsconfig-paths and retry.
+                if (isModuleNotFoundError(err) &&
+                    !pathsRegistered &&
+                    !disableTsConfigPaths &&
+                    resolvedTsConfigPath) {
+                    logFallback(filePath, err, 'Module not found; registering tsconfig-paths and retrying.');
+                    cleanups.push(registerTsConfigPaths(resolvedTsConfigPath));
+                    pathsRegistered = true;
+                    continue;
+                }
+                // Heavy fallback: register swc/ts-node (+ paths) and retry. Triggered
+                // by:
+                //   - strip-types failure (`ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`)
+                //   - module resolution failure that tsconfig-paths alone can't fix
+                //     (extensionless `./foo` -> `./foo.ts`)
+                //   - SyntaxError in a `.cts`/`.cjs` file (ESM syntax in a forced-CJS
+                //     file). swc-node compiles ESM->CJS regardless of extension.
+                //   - SyntaxError from Node parsing a `.ts` config with ESM syntax as
+                //     CJS. swc/ts-node preserves the pre-v23 behavior for these files.
+                //   - ReferenceError from Node treating a `.ts`/`.mts` config as ESM
+                //     when it contains legacy CJS `require`.
+                //   - SyntaxError from native ESM linkage when generated TS config
+                //     imports a type-only symbol as a runtime named export.
+                if ((isNativeTypeStripError(err) ||
+                    isModuleNotFoundError(err) ||
+                    isCjsSyntaxError(err, filePath) ||
+                    isTsEsmSyntaxError(err, filePath) ||
+                    isRequireInEsmScopeError(err, filePath) ||
+                    isTsEsmNamedExportLinkageError(err, filePath)) &&
+                    !transpilerRegistered) {
+                    logFallback(filePath, err, isNativeTypeStripError(err)
+                        ? 'Native Node.js TypeScript stripping failed; falling back to swc/ts-node + tsconfig-paths.'
+                        : isCjsSyntaxError(err, filePath)
+                            ? 'ESM syntax in forced-CJS file; falling back to swc/ts-node + tsconfig-paths.'
+                            : isTsEsmSyntaxError(err, filePath)
+                                ? 'ESM syntax in TypeScript file parsed as CommonJS; falling back to swc/ts-node + tsconfig-paths.'
+                                : isRequireInEsmScopeError(err, filePath)
+                                    ? 'CommonJS require in native ESM TypeScript file; falling back to swc/ts-node + tsconfig-paths.'
+                                    : isTsEsmNamedExportLinkageError(err, filePath)
+                                        ? 'Native ESM named export linkage failed; falling back to swc/ts-node + tsconfig-paths.'
+                                        : 'Module not found after tsconfig-paths; falling back to swc/ts-node + tsconfig-paths.');
+                    registerTranspilerFallback(err);
+                    continue;
+                }
+                throw augmentLoadFailure(filePath, err);
+            }
+        }
+    }
+    finally {
+        for (const fn of cleanups)
+            fn();
+    }
+}
+/**
+ * Plain `require()` with a lazy `tsconfig-paths` fallback. Use for files that
+ * are NOT TypeScript (no transpilation needed) but may still import workspace
+ * packages through TS path aliases (e.g. a `.js` changelog renderer that
+ * `require`s `@my-org/lib`).
+ *
+ * `tsconfig-paths` is only registered after the first `require()` fails with
+ * a module-resolution error, so workspaces that resolve aliases through
+ * package-manager symlinks pay nothing. Set `NX_DISABLE_TSCONFIG_PATHS=true`
+ * to skip the fallback entirely.
+ *
+ * @returns the loaded module
+ */
+function requireWithTsconfigFallback(filePath, tsConfigPath) {
+    try {
+        return require(filePath);
+    }
+    catch (err) {
+        if (!isModuleNotFoundError(err) || disableTsConfigPaths) {
+            throw err;
+        }
+        const resolvedTsConfigPath = tsConfigPath ?? (0, typescript_1.getRootTsConfigPath)();
+        if (!resolvedTsConfigPath) {
+            throw err;
+        }
+        const cleanup = registerTsConfigPaths(resolvedTsConfigPath);
+        try {
+            delete require.cache[require.resolve(filePath)];
+        }
+        catch {
+            // require.resolve may throw if the failed load never reached cache
+        }
+        try {
+            return require(filePath);
+        }
+        finally {
+            cleanup();
+        }
+    }
+}
+/**
+ * Append the `NX_PREFER_NODE_STRIP_TYPES=false` opt-out hint so users know
+ * there's an escape hatch for cases native strip can't reach (e.g. ESM with
+ * top-level await + unsupported TS syntax). Skipped for:
+ *   - ESM-redispatch signals callers expect to handle
+ *     (`ERR_REQUIRE_ESM`, `ERR_REQUIRE_ASYNC_MODULE`)
+ *   - plain module-resolution failures (`MODULE_NOT_FOUND`,
+ *     `ERR_MODULE_NOT_FOUND`) - disabling strip-types doesn't fix a missing
+ *     module, the hint just misleads.
+ */
+function augmentLoadFailure(filePath, err) {
+    if (!(err instanceof Error))
+        return err;
+    const code = err.code;
+    if (code === 'ERR_REQUIRE_ESM' ||
+        code === 'ERR_REQUIRE_ASYNC_MODULE' ||
+        code === 'MODULE_NOT_FOUND' ||
+        code === 'ERR_MODULE_NOT_FOUND') {
+        return err;
+    }
+    if (err.message.includes(NX_PREFER_NODE_STRIP_TYPES_DOCS_URL)) {
+        return err;
+    }
+    err.message = `${err.message}\n\n${logger_1.NX_PREFIX} Failed to load ${filePath} under Node's native TypeScript stripping. ${STRIP_TYPES_OPT_OUT_HINT}`;
+    return err;
+}
+function logFallback(filePath, err, summary) {
+    if (process.env.NX_VERBOSE_LOGGING !== 'true') {
+        return;
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    logger_1.logger.warn((0, logger_1.stripIndent)(`${logger_1.NX_PREFIX} ${summary} (${filePath})
+  ${message}`));
+}
 /**
  * Register ts-node or swc-node given a set of compiler options.
  *
@@ -266,7 +651,7 @@ function registerTranspiler(compilerOptions, tsConfigRaw) {
     const transpiler = getTranspiler(compilerOptions, tsConfigRaw);
     if (!transpiler) {
         // If Node.js natively supports TypeScript (22.6+), no transpiler is needed.
-        // Don't warn — Node will handle .ts files via type stripping.
+        // Don't warn - Node will handle .ts files via type stripping.
         if (!nodeSupportsNativeTypescript) {
             warnNoTranspiler();
         }
@@ -290,6 +675,16 @@ function registerTsConfigPaths(tsConfigPath) {
          * can be imported and used within project
          */
         if (tsConfigResult.resultType === 'success') {
+            // Short-circuit when the tsconfig has no `paths` entries. Installing
+            // tsconfig-paths' resolver hook adds a per-require cost on every
+            // module load; in package-manager-workspace setups (which resolve via
+            // symlinks instead of TS path mappings), the hook never has anything
+            // to do. Avoid paying that overhead on workspaces that don't use
+            // `paths`.
+            if (!tsConfigResult.paths ||
+                Object.keys(tsConfigResult.paths).length === 0) {
+                return () => { };
+            }
             return tsconfigPaths.register({
                 baseUrl: resolvePathsBaseUrl(tsConfigPath),
                 paths: tsConfigResult.paths,

package/dist/src/plugins/js/utils/typescript.d.ts

@@ -13,4 +13,11 @@ export declare function readTsConfigOptions(tsConfigPath: string): ts.CompilerOp
 export declare function resolveModuleByImport(importExpr: string, filePath: string, tsConfigPath: string): string;
 export declare function getRootTsConfigFileName(): string | null;
 export declare function getRootTsConfigPath(): string | null;
+export declare function getRootTsConfigCustomConditions(root?: string): string[];
+/**
+ * Conditions list for `resolve.exports`: workspace `customConditions` plus
+ * `development` as backward-compat for workspaces not yet migrated by
+ * `migrate-development-custom-condition` (21.5).
+ */
+export declare function getRootTsConfigResolveExportsConditions(root?: string): string[];
 export declare function findNodes(node: Node, kind: SyntaxKind | SyntaxKind[], max?: number): Node[];

package/dist/src/plugins/js/utils/typescript.js

@@ -6,6 +6,8 @@ exports.readTsConfigOptions = readTsConfigOptions;
 exports.resolveModuleByImport = resolveModuleByImport;
 exports.getRootTsConfigFileName = getRootTsConfigFileName;
 exports.getRootTsConfigPath = getRootTsConfigPath;
+exports.getRootTsConfigCustomConditions = getRootTsConfigCustomConditions;
+exports.getRootTsConfigResolveExportsConditions = getRootTsConfigResolveExportsConditions;
 exports.findNodes = findNodes;
 const workspace_root_1 = require("../../../utils/workspace-root");
 const fs_1 = require("fs");
@@ -74,6 +76,43 @@ function getRootTsConfigPath() {
     const tsConfigFileName = getRootTsConfigFileName();
     return tsConfigFileName ? (0, path_1.join)(workspace_root_1.workspaceRoot, tsConfigFileName) : null;
 }
+const customConditionsCache = new Map();
+function getRootTsConfigCustomConditions(root = workspace_root_1.workspaceRoot) {
+    if (customConditionsCache.has(root)) {
+        return customConditionsCache.get(root);
+    }
+    // Resolve via the TypeScript API rather than a raw JSON read so that
+    // `customConditions` inherited through `extends` chains are honored —
+    // matches what TypeScript itself sees when resolving package exports.
+    let conditions = [];
+    for (const name of ['tsconfig.base.json', 'tsconfig.json']) {
+        const tsConfigPath = (0, path_1.join)(root, name);
+        if (!(0, fs_1.existsSync)(tsConfigPath)) {
+            continue;
+        }
+        try {
+            const options = readTsConfigOptions(tsConfigPath);
+            if (Array.isArray(options.customConditions)) {
+                conditions = options.customConditions.filter((c) => typeof c === 'string');
+            }
+        }
+        catch { }
+        break;
+    }
+    customConditionsCache.set(root, conditions);
+    return conditions;
+}
+/**
+ * Conditions list for `resolve.exports`: workspace `customConditions` plus
+ * `development` as backward-compat for workspaces not yet migrated by
+ * `migrate-development-custom-condition` (21.5).
+ */
+function getRootTsConfigResolveExportsConditions(root = workspace_root_1.workspaceRoot) {
+    const conditions = getRootTsConfigCustomConditions(root);
+    return conditions.includes('development')
+        ? conditions
+        : [...conditions, 'development'];
+}
 function findNodes(node, kind, max = Infinity) {
     if (!node || max == 0) {
         return [];

package/dist/src/plugins/package-json/create-nodes.d.ts

@@ -1,6 +1,7 @@
 import { NxJsonConfiguration } from '../../config/nx-json';
 import type { ProjectConfiguration } from '../../config/workspace-json-project-json';
 import { PackageJson } from '../../utils/package-json';
+import { PackageManagerCommands } from '../../utils/package-manager';
 import { CreateNodesV2 } from '../../project-graph/plugins';
 import { PackageJsonConfigurationCache } from '../../../plugins/package-json';
 export declare const createNodesV2: CreateNodesV2;
@@ -12,12 +13,12 @@ type PackageJsonPatterns = {
     negativeLookup: Record<string, boolean>;
 };
 export declare function buildPackageJsonWorkspacesMatcher(patterns: PackageJsonPatterns): (p: any) => boolean;
-export declare function createNodeFromPackageJson(pkgJsonPath: string, workspaceRoot: string, cache: PackageJsonConfigurationCache, isInPackageManagerWorkspaces: boolean): {
+export declare function createNodeFromPackageJson(pkgJsonPath: string, workspaceRoot: string, cache: PackageJsonConfigurationCache, isInPackageManagerWorkspaces: boolean, packageManagerCommand: PackageManagerCommands): {
     projects: {
         [x: string]: ProjectConfiguration;
     };
 };
-export declare function buildProjectConfigurationFromPackageJson(packageJson: PackageJson, workspaceRoot: string, packageJsonPath: string, nxJson: NxJsonConfiguration, isInPackageManagerWorkspaces: boolean): ProjectConfiguration & {
+export declare function buildProjectConfigurationFromPackageJson(packageJson: PackageJson, workspaceRoot: string, packageJsonPath: string, nxJson: NxJsonConfiguration, isInPackageManagerWorkspaces: boolean, packageManagerCommand: PackageManagerCommands): ProjectConfiguration & {
     name: string;
 };
 /**