feat: replace tsnode with tsx for parsing user configuration in all cases

Author: AtofStryker

Diff for: .circleci/workflows.yml

@@ -38,7 +38,7 @@ mainBuildFilters: &mainBuildFilters
         - /^release\/\d+\.\d+\.\d+$/
         # use the following branch as well to ensure that v8 snapshot cache updates are fully tested
         - 'update-v8-snapshot-cache-on-develop'
-        - 'chore/update_mobx_decoratorless'
+        - 'feat/replace_tsnode_for_tsx_config_process'
 
 # usually we don't build Mac app - it takes a long time
 # but sometimes we want to really confirm we are doing the right thing
@@ -49,7 +49,7 @@ macWorkflowFilters: &darwin-workflow-filters
       - equal: [ develop, << pipeline.git.branch >> ]
       # use the following branch as well to ensure that v8 snapshot cache updates are fully tested
       - equal: [ 'update-v8-snapshot-cache-on-develop', << pipeline.git.branch >> ]
-      - equal: [ 'chore/update_mobx_decoratorless', << pipeline.git.branch >> ]
+      - equal: [ 'feat/replace_tsnode_for_tsx_config_process', << pipeline.git.branch >> ]
       - matches:
           pattern: /^release\/\d+\.\d+\.\d+$/
           value: << pipeline.git.branch >>
@@ -60,7 +60,7 @@ linuxArm64WorkflowFilters: &linux-arm64-workflow-filters
       - equal: [ develop, << pipeline.git.branch >> ]
       # use the following branch as well to ensure that v8 snapshot cache updates are fully tested
       - equal: [ 'update-v8-snapshot-cache-on-develop', << pipeline.git.branch >> ]
-      - equal: [ 'chore/update_mobx_decoratorless', << pipeline.git.branch >> ]
+      - equal: [ 'feat/replace_tsnode_for_tsx_config_process', << pipeline.git.branch >> ]
       - matches:
           pattern: /^release\/\d+\.\d+\.\d+$/
           value: << pipeline.git.branch >>
@@ -83,7 +83,7 @@ windowsWorkflowFilters: &windows-workflow-filters
       - equal: [ develop, << pipeline.git.branch >> ]
       # use the following branch as well to ensure that v8 snapshot cache updates are fully tested
       - equal: [ 'update-v8-snapshot-cache-on-develop', << pipeline.git.branch >> ]
-      - equal: [ 'chore/update_mobx_decoratorless', << pipeline.git.branch >> ]
+      - equal: [ 'feat/replace_tsnode_for_tsx_config_process', << pipeline.git.branch >> ]
       - matches:
           pattern: /^release\/\d+\.\d+\.\d+$/
           value: << pipeline.git.branch >>
@@ -157,7 +157,7 @@ commands:
           name: Set environment variable to determine whether or not to persist artifacts
           command: |
             echo "Setting SHOULD_PERSIST_ARTIFACTS variable"
-            echo 'if ! [[ "$CIRCLE_BRANCH" != "develop" && "$CIRCLE_BRANCH" != "release/"* && "$CIRCLE_BRANCH" != "chore/update_mobx_decoratorless" ]]; then
+            echo 'if ! [[ "$CIRCLE_BRANCH" != "develop" && "$CIRCLE_BRANCH" != "release/"* && "$CIRCLE_BRANCH" != "feat/replace_tsnode_for_tsx_config_process" ]]; then
                 export SHOULD_PERSIST_ARTIFACTS=true
             fi' >> "$BASH_ENV"
   # You must run `setup_should_persist_artifacts` command and be using bash before running this command

Diff for: cli/CHANGELOG.md

@@ -8,6 +8,10 @@ _Released 07/01/2025 (PENDING)_
 - Removed support for Node.js 18 and Node.js 23. Addresses [#31302](https://github.com/cypress-io/cypress/issues/31302).
 - Removed support for [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol) with the [firefox](https://www.mozilla.org/) browser. Addresses [#31189](https://github.com/cypress-io/cypress/issues/31189).
 
+**Features:**
+
+- [`tsx`](https://tsx.is/) is now used in all cases to run the Cypress config, replacing [ts-node](https://github.com/TypeStrong/ts-node) for TypeScript and Node for commonjs/ESM. This should allow for more interoperability for users who are using any variant of ES Modules. Addresses [#30954](https://github.com/cypress-io/cypress/issues/30954), [#30925](https://github.com/cypress-io/cypress/issues/30925), and [#31185](https://github.com/cypress-io/cypress/issues/31185).
+
 ## 14.3.1
 
 _Released 4/22/2025 (PENDING)_

Diff for: packages/data-context/package.json

@@ -39,6 +39,7 @@
     "execa": "1.0.0",
     "front-matter": "^4.0.2",
     "fs-extra": "8.1.0",
+    "get-tsconfig": "4.10.0",
     "getenv": "1.0.0",
     "globby": "^11.0.1",
     "graphql": "^15.5.1",
@@ -60,6 +61,7 @@
     "server-destroy": "1.0.1",
     "simple-git": "^3.27.0",
     "stringify-object": "^3.0.0",
+    "tsx": "4.19.3",
     "underscore.string": "^3.3.6",
     "wonka": "^4.0.15"
   },

Diff for: packages/data-context/src/actions/MigrationActions.ts

@@ -38,7 +38,7 @@ import { hasTypeScriptInstalled, toPosix } from '../util'
 
 const debug = debugLib('cypress:data-context:MigrationActions')
 
-const tsNode = toPosix(require.resolve('@packages/server/lib/plugins/child/register_ts_node'))
+const tsxCjs = toPosix(require.resolve('tsx/cjs'))
 
 export function getConfigWithDefaults (legacyConfig: any) {
   const newConfig = _.cloneDeep(legacyConfig)
@@ -99,20 +99,20 @@ export async function processConfigViaLegacyPlugins (projectRoot: string, legacy
     const configProcessArgs = ['--projectRoot', projectRoot, '--file', cwd]
     const CHILD_PROCESS_FILE_PATH = require.resolve('@packages/server/lib/plugins/child/require_async_child')
 
-    // use ts-node if they've got typescript installed
+    // use tsx if they've got typescript installed
     // this matches the 9.x behavior, which is what we want for
     // processing legacy pluginsFile (we never supported `"type": "module") in 9.x.
     if (hasTypeScriptInstalled(projectRoot)) {
-      const tsNodeLoader = `--require "${tsNode}"`
+      const tsxLoader = `--require "${tsxCjs}"`
 
       if (!childOptions.env) {
         childOptions.env = {}
       }
 
       if (childOptions.env.NODE_OPTIONS) {
-        childOptions.env.NODE_OPTIONS += ` ${tsNodeLoader}`
+        childOptions.env.NODE_OPTIONS += ` ${tsxLoader}`
       } else {
-        childOptions.env.NODE_OPTIONS = tsNodeLoader
+        childOptions.env.NODE_OPTIONS = tsxLoader
       }
     }
 

Diff for: packages/data-context/src/data/ProjectConfigIpc.ts

@@ -3,25 +3,24 @@ import { CypressError, getError } from '@packages/errors'
 import type { FullConfig, TestingType } from '@packages/types'
 import { ChildProcess, fork, ForkOptions, spawn } from 'child_process'
 import EventEmitter from 'events'
-import fs from 'fs-extra'
 import path from 'path'
 import inspector from 'inspector'
 import debugLib from 'debug'
+import { getTsconfig } from 'get-tsconfig'
 import { autoBindDebug, hasTypeScriptInstalled, toPosix } from '../util'
 import _ from 'lodash'
-import { pathToFileURL } from 'url'
 import os from 'os'
 import semver from 'semver'
 import type { OTLPTraceExporterCloud } from '@packages/telemetry'
 import { telemetry, encodeTelemetryContext } from '@packages/telemetry'
 
 const pkg = require('@packages/root')
 const debug = debugLib(`cypress:lifecycle:ProjectConfigIpc`)
+const debugVerbose = debugLib(`cypress-verbose:lifecycle:ProjectConfigIpc`)
 
 const CHILD_PROCESS_FILE_PATH = require.resolve('@packages/server/lib/plugins/child/require_async_child')
 
-const tsNodeEsm = pathToFileURL(require.resolve('ts-node/esm/transpile-only')).href
-const tsNode = toPosix(require.resolve('@packages/server/lib/plugins/child/register_ts_node'))
+const tsx = toPosix(require.resolve('tsx'))
 
 export type IpcHandler = (ipc: ProjectConfigIpc) => void
 
@@ -262,10 +261,8 @@ export class ProjectConfigIpc extends EventEmitter {
 
   private forkConfigProcess () {
     const configProcessArgs = ['--projectRoot', this.projectRoot, '--file', this.configFilePath]
-    // allow the use of ts-node in subprocesses tests by removing the env constant from it
-    // without this line, packages/ts/register.js never registers the ts-node module for config and
-    // run_plugins can't use the config module.
-    const env = _.omit(process.env, 'CYPRESS_INTERNAL_E2E_TESTING_SELF')
+    // we do NOT want telemetry enabled within our cy-in-cy tests as it isn't configured to handled it
+    const env = _.omit(process.env, 'CYPRESS_INTERNAL_E2E_TESTING_SELF', 'CYPRESS_INTERNAL_ENABLE_TELEMETRY')
 
     env.NODE_OPTIONS = process.env.ORIGINAL_NODE_OPTIONS || ''
 
@@ -279,86 +276,71 @@ export class ProjectConfigIpc extends EventEmitter {
     if (inspector.url()) {
       childOptions.execArgv = _.chain(process.execArgv.slice(0))
       .remove('--inspect-brk')
+      // NOTE: The IDE in which you are working likely will not let attach to this process until it is running if using the --inspect option
+      // If needing to debug the child process (webpack-dev-server/vite-dev-server/webpack-preprocessor(s)/config loading), you may want to use --inspect-brk instead
+      // as it will NOT execute that process until you attach the debugger to it.
       .push(`--inspect=${process.debugPort + 1}`)
       .value()
     }
 
-    debug('fork child process %o', { CHILD_PROCESS_FILE_PATH, configProcessArgs, childOptions: _.omit(childOptions, 'env') })
-
-    let isProjectUsingESModules = false
+    /**
+     * Before the introduction of tsx, Cypress used ts-node (@see https://github.com/TypeStrong/ts-node) with native node to try and load the user's cypress.config.ts file.
+     * This presented problems because the Cypress node runtime runs in commonjs, which may not be compatible with the user's cypress.config.ts and tsconfig.json.
+     * To mitigate the aforementioned runtime incompatibility, we used to force TypeScript options for the user in order to load their config inside the our node context
+     * via a child process, which lead to clashes and issues (outlined in the comments below).
+     * This is best explained historically in our docs which a screenshot can be see in @see https://github.com/cypress-io/cypress/issues/30426#issuecomment-2805204540 and can be seen
+     * in an older version of the Cypress codebase (@see https://github.com/cypress-io/cypress/blob/v14.3.0/packages/server/lib/plugins/child/ts_node.js#L24)
+     *
+     * Attempted workarounds with ts-node and node: @see https://github.com/cypress-io/cypress/pull/28709
+     * Example continued end user issues: @see https://github.com/cypress-io/cypress/issues/30954 and @see https://github.com/cypress-io/cypress/issues/30925
+     * Spike into ts-node alternatives (a lot of useful comments on tsx): @see https://github.com/cypress-io/cypress/issues/30426
+     * feature issue to replace ts-node as our end user TypeScript loader: @see https://github.com/cypress-io/cypress/issues/31185
+     *
+     * tsx (@see https://tsx.is/) is able to work with both CommonJS and ESM at the same time ( @see https://tsx.is/#seamless-cjs-%E2%86%94-esm-imports), which solves the problem of interoperability that
+     * Cypress faced with ts-node and really just node itself. We no longer need experimental node flags and ts-node permutations to load the user's config file.
+     * We can use tsx to load just about anything, including JavaScript files (@see https://github.com/privatenumber/ts-runtime-comparison)!
+     */
 
-    try {
-      // TODO: convert this to async FS methods
-      // eslint-disable-next-line no-restricted-syntax
-      const pkgJson = fs.readJsonSync(path.join(this.projectRoot, 'package.json'))
-
-      isProjectUsingESModules = pkgJson.type === 'module'
-    } catch (e) {
-      // project does not have `package.json` or it was not found
-      // reasonable to assume not using es modules
-    }
+    debug('fork child process %o', { CHILD_PROCESS_FILE_PATH, configProcessArgs, childOptions: _.omit(childOptions, 'env') })
 
     if (!childOptions.env) {
       childOptions.env = {}
     }
 
-    // If they've got TypeScript installed, we can use
-    // ts-node for CommonJS
-    // ts-node/esm for ESM
-    if (hasTypeScriptInstalled(this.projectRoot)) {
+    /**
+     * use --import for node 20.6.0 and above as --import is supported
+     * use --loader for node under 20.6.0
+     * @see https://tsx.is/dev-api/node-cli#node-js-cli
+     */
+    let tsxLoader = this.nodeVersion && semver.lt(this.nodeVersion, '20.6.0') ? `--loader ${tsx}` : `--import ${tsx}`
+
+    // If they've got TypeScript installed, we can use tsx for CommonJS and ESM.
+    // @see https://tsx.is/dev-api/node-cli#node-js-cli
+    const userHasTypeScriptInstalled = hasTypeScriptInstalled(this.projectRoot)
+
+    if (userHasTypeScriptInstalled) {
       debug('found typescript in %s', this.projectRoot)
-      if (isProjectUsingESModules) {
-        debug(`using --experimental-specifier-resolution=node with --loader ${tsNodeEsm}`)
-        // Use the ts-node/esm loader so they can use TypeScript with `"type": "module".
-        // The loader API is experimental and will change.
-        // The same can be said for the other alternative, esbuild, so this is the
-        // best option that leverages the existing modules we bundle in the binary.
-        // @see ts-node esm loader https://typestrong.org/ts-node/docs/usage/#node-flags-and-other-tools
-        // @see Node.js Loader API https://nodejs.org/api/esm.html#customizing-esm-specifier-resolution-algorithm
-        let tsNodeEsmLoader = `--experimental-specifier-resolution=node --loader ${tsNodeEsm}`
-
-        // starting in nodejs 20.19.0 and 22.7.0, the --experimental-detect-module option is now enabled by default.
-        // We need to disable it with the --no-experimental-detect-module flag.
-        // @see https://github.com/cypress-io/cypress/issues/30084
-        if (this.nodeVersion && (semver.gte(this.nodeVersion, '22.7.0') || semver.satisfies(this.nodeVersion, '>= 20.19.0 < 21.0.0'))) {
-          debug(`detected node version ${this.nodeVersion}, adding --no-experimental-detect-module option to child_process NODE_OPTIONS.`)
-          tsNodeEsmLoader = `${tsNodeEsmLoader} --no-experimental-detect-module`
-        }
-
-        // starting in nodejs 20.19.0 and 22.12.0, the --experimental-require-module option is now enabled by default.
-        // We need to disable it with the --no-experimental-require-module flag.
-        // @see https://github.com/cypress-io/cypress/issues/30715
-        if (this.nodeVersion && (semver.gte(this.nodeVersion, '22.12.0') || semver.satisfies(this.nodeVersion, '>= 20.19.0 < 21.0.0'))) {
-          debug(`detected node version ${this.nodeVersion}, adding --no-experimental-require-module option to child_process NODE_OPTIONS.`)
-          tsNodeEsmLoader = `${tsNodeEsmLoader} --no-experimental-require-module`
-        }
-
-        if (childOptions.env.NODE_OPTIONS) {
-          childOptions.env.NODE_OPTIONS += ` ${tsNodeEsmLoader}`
-        } else {
-          childOptions.env.NODE_OPTIONS = tsNodeEsmLoader
-        }
+
+      // TODO: get the tsconfig.json that applies to the users cypress.config.ts file
+      // right now, we are just using the tsconfig.json we find in the project root
+      const tsConfigIfExists = getTsconfig(this.projectRoot)
+
+      if (tsConfigIfExists) {
+        debug(`tsconfig.json found at ${tsConfigIfExists.path}`)
+        childOptions.env.TSX_TSCONFIG_PATH = tsConfigIfExists.path
+
+        debugVerbose(`tsconfig.json parsed as follows: %o`, tsConfigIfExists.config)
       } else {
-        // Not using ES Modules (via "type": "module"),
-        // so we just register the standard ts-node module
-        // to handle TypeScript that is compiled to CommonJS.
-        // We do NOT use the `--loader` flag because we have some additional
-        // custom logic for ts-node when used with CommonJS that needs to be evaluated
-        // so we need to load and evaluate the hook first using the `--require` module API.
-        const tsNodeLoader = `--require "${tsNode}"`
-
-        debug(`using cjs with --require ${tsNode}`)
-
-        if (childOptions.env.NODE_OPTIONS) {
-          childOptions.env.NODE_OPTIONS += ` ${tsNodeLoader}`
-        } else {
-          childOptions.env.NODE_OPTIONS = tsNodeLoader
-        }
+        debug(`No tsconfig.json found! Attempting to parse file without tsconfig.json.`)
       }
+    }
+
+    debug(`using generic ${tsxLoader} for esm and cjs ${userHasTypeScriptInstalled ? 'with TypeScript' : ''}.`)
+
+    if (childOptions.env.NODE_OPTIONS) {
+      childOptions.env.NODE_OPTIONS += ` ${tsxLoader}`
     } else {
-      // Just use Node's built-in ESM support.
-      // TODO: Consider using userland `esbuild` with Node's --loader API to handle ESM.
-      debug(`no typescript found, just use regular Node.js`)
+      childOptions.env.NODE_OPTIONS = tsxLoader
     }
 
     const telemetryCtx = encodeTelemetryContext({ context: telemetry.getActiveContextObject(), version: pkg.version })

Diff for: packages/data-context/src/sources/ErrorDataSource.ts

@@ -24,7 +24,7 @@ export class ErrorDataSource {
       return null
     }
 
-    // If we saw a TSError,  or a esbuild error we will extract the error location from the message
+    // If we saw a TransformError, or a esbuild error we will extract the error location from the message
     const compilerErrorLocation = source.cypressError.originalError?.compilerErrorLocation
 
     let line: number | null | undefined
@@ -38,7 +38,8 @@ export class ErrorDataSource {
     } else {
       // Skip any stack trace lines which come from node:internal code
       const stackLines = stackUtils.getStackLines(source.cypressError.stack ?? '')
-      const filteredStackLines = stackLines.filter((stackLine) => !stackLine.includes('node:electron') && !stackLine.includes('node:internal') && !stackLine.includes('source-map-support'))
+      // we want to filter out any tsx transformation code in the stack to help identify the error
+      const filteredStackLines = stackLines.filter((stackLine) => !stackLine.includes('node:electron') && !stackLine.includes('node:internal') && !stackLine.includes('source-map-support') && !stackLine.includes('/node_modules/tsx/dist/register'))
       const parsedLine = stackUtils.parseStackLine(filteredStackLines[0] ?? '')
 
       if (parsedLine) {