feat: replace `ts-node` with `tsx` for parsing user configuration #31520

AtofStryker · 2025-04-15T18:20:08Z

Closes

Closes feat: replace ts-node with tsx for user configuration parsing and cypress runtime #31185
Closes Cypress forces an invalid moduleResolution value for Typescript 5.7.3; it is unable to start #30954
Closes cypress open not working #30925
Closes TypeScript and package.json type module (ESM) shows "ExperimentalWarning: --experimental-loader" #30318 (no longer need the --experimental-loader option)
Closes Spurious TypeScript warnings in monorepo with JavaScript component testing project #30915 (no longer need the --experimental-loader option)
Closes Use unjs/jiti instead of ts-node #30718 (tsx will be used to replace ts-node instead of jiti)
Closes Cypress fails to start if tsconfig contains "allowImportingTsExtensions": true #28442
Closes Your configFile is invalid [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" #27450
Closes Scaffolded project with "tsc --init" + "type": "module" fails to compile due to conflicting module/commonjs #27359
Closes Unable to supply own ts-node ignore values in tsconfig.json #26606
Closes Cannot consume ES module based cypress config when using Yarn 3 #22747
Closes Yarn 3 + cypress.config.ts does not work #25958
Closes Yarn 3 does not work with type=module and cypress.config.js #25959
Closes After Spec API TypeScript Code breaks the config.ts file - [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" #23141
Closes Error [ERR_REQUIRE_ESM]: Must use import to load ES Module error thrown #8090
Closes "Couldn't find tsconfig.json" error in JavaScript monorepo #30907
Closes Error message printed to the console: Couldn't find tsconfig.json. tsconfig-paths will be skipped #22273 (duplicate)
Closes Do not show tsconfig.json warning in terminal for TS projects without tsconfig.json #21805 (duplicate)
Closes Missing baseUrl in compilerOptions. tsconfig-paths will be skipped #15724 (duplicate)

Side effect of not using Node as the loader

Reinforces Your configFile is invalid with Node.js 22.12.0 #30715 (don't need to worry about the --no-experimental-require-module as we aren't using Node directly as the file loader. see https://nodejs.org/en/blog/release/v22.12.0#requireesm-is-now-enabled-by-default)
-Reinforces ERR_INTERNAL_ASSERTION with Node.js >= v22.1.0 and experimental-detect-module set #30101 (don't need to worry about the --no-experimental-detect-module option as we aren't using Node directly as the file loader. see https://github.com/nodejs/node/blob/main/doc/changelogs/CHANGELOG_V22.md?rgh-link-date=2024-08-22T15%3A58%3A27Z#module-syntax-detection-is-now-enabled-by-default)

Additional details

Introduces tsx as the new tool of choice to load and parse the end user's cypress.config.(js|ts), replacing ts-node. This solves a lot of issues around ESM projects using Cypress as we are now able to more easily run ESM based cypress configurations (TypeScript or JavaScript) within the Cypress child process. This means we don't need ts-node work arounds to try to run the user's config as commonjs, which results in configuration clashes in TypeScript, nor do we need nodes experimental loaders / options to run ESM JavaScript projects.

Steps to test

Go through some of the reproductions in the aforementioned issues and run the pre release binary installed in the project. Notice the project is now able to run

How has the user experience changed?

The TypeScript / ESM experience is greatly improved as users are now able to run Cypress in their project without having to commit to hacky workarounds!

PR Tasks

Have tests been added/updated? added in 3dfeeb9
Has a PR for user-facing changes been opened in cypress-documentation? chore: update typescript docs to tsx cypress-documentation#6155
Have API changes been updated in the type definitions? (N/A)

cypress · 2025-04-15T19:50:40Z

cypress Run #62004

Run Properties: Passed #62004 • 0a526aab83: updated node versions in project config ipc tests to remove 18 and test threshol...

Project	`cypress`
Branch Review	`feat/replace_tsnode_for_tsx_config_process`
Run status	`Passed #62004`
Run duration	`16m 42s`
Commit	`0a526aab83: updated node versions in project config ipc tests to remove 18 and test threshol...`
Committer	`AtofStryker`
View all properties for this run ↗︎

Test results
Failures	`0`
Flaky	`1`
Pending	`29`
Skipped	`0`
Passing	`794`
View all changes introduced in this branch ↗︎

UI Coverage `63.64%`
Untested elements	`30`
Tested elements	`56`

Accessibility `96.22%`
Failed rules	`0 critical` `4 serious` `1 moderate` `0 minor`
Failed elements	`195`

…ases

…cypress 15 and allows us to not include the 18.19.0 workaround to use --import with tsx inside the ProjectConfigIpc

…s absolute drive paths are not recognized as a file protocol in the node context

… to this PR and should be merged into develop)

…not work but now do with tsx

…eat/replace_tsnode_for_tsx_config_process

packages/app/cypress/e2e/specs.cy.ts

packages/data-context/src/actions/MigrationActions.ts

jennifer-shehane · 2025-04-23T20:28:07Z

packages/data-context/src/data/ProjectConfigIpc.ts

+    /**
+     * 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)!
+     */


Is there value in having comments about code that's no longer in the repo here? I'm not understanding how I would find how Cypress used to work valuable here.

I felt like we should capture it here someplace because why else are we using different tooling to register the user config than how we do it everywhere else in the repo? At least until we unify it maybe? or link out in the comments

I want this captured someplace but I don't think this is the best place. any ideas?

packages/data-context/src/data/ProjectConfigIpc.ts

jennifer-shehane · 2025-04-23T20:36:23Z

packages/data-context/src/sources/ErrorDataSource.ts

 import type { DataContext } from '..'

+const tsxCodeFrameFilter = '/node_modules/tsx/dist/register'


Would we be able to catch if this path changed in the future?

I would think the transform error tests in the app package cy-in-cy tests would error since the codeFrame would be broken and missing, which the test checks for https://github.com/cypress-io/cypress/blob/develop/packages/launchpad/cypress/e2e/config-files-error-handling.cy.ts#L204

packages/data-context/src/sources/ErrorDataSource.ts

packages/data-context/test/unit/data/ProjectConfigIpc.spec.ts

…eat/replace_tsnode_for_tsx_config_process

Dismissing my comments as addressed

…_process

…om:cypress-io/cypress into feat/replace_tsnode_for_tsx_config_process

AtofStryker · 2025-04-25T18:52:38Z

packages/server/lib/browsers/index.ts

@@ -95,13 +95,13 @@ async function setFocus () {
 async function getBrowserLauncher (browser: Browser, browsers: FoundBrowser[]): Promise<BrowserLauncher> {
  debug('getBrowserLauncher %o', { browser })

-  if (browser.name === 'electron') return await import('./electron')
+  if (browser.name === 'electron') return require('./electron')


todo: can we type this?

it's somewhat irrelevant but we could also explore just importing the files at the top and returning them here

packages/server/lib/plugins/child/run_require_async_child.js

packages/data-context/test/unit/data/ProjectConfigIpc.spec.ts

AtofStryker · 2025-04-25T19:40:08Z

system-tests/test/yarn_v3.1.1_pnp_spec.ts

    browser: 'electron',
    project: 'yarn-v3.1.1-pnp',
-    onRun: async (run) => {
-      await run({


this one is a bit bizarre, but the --dev mode doesn't work exactly correct here has we are using ts-node to register the typescript options, which pollutes the tsconfig with allowSyntheticDefaultImports and was causing the test to fail. Not sure why we need dev mode here, but it works fine without it to completely isolate us from ts-node in our system tests

…st threshold / latest values. Removed redundant comments on ts-node.

ryanthemanuel · 2025-04-29T14:17:42Z

cli/CHANGELOG.md

@@ -10,6 +10,10 @@ _Released 07/01/2025 (PENDING)_
 - 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).
 - The Cypress configuration wizard for Component Testing supports TypeScript 5.0 or greater. Addresses [#31187](https://github.com/cypress-io/cypress/issues/31187).

+**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 [#8090](https://github.com/cypress-io/cypress/issues/8090), [#15724](https://github.com/cypress-io/cypress/issues/15724), [#21805](https://github.com/cypress-io/cypress/issues/21805), [#22273](https://github.com/cypress-io/cypress/issues/22273), [#22747](https://github.com/cypress-io/cypress/issues/22747), [#23141](https://github.com/cypress-io/cypress/issues/23141), [#25958](https://github.com/cypress-io/cypress/issues/25958), [#25959](https://github.com/cypress-io/cypress/issues/25959), [#26606](https://github.com/cypress-io/cypress/issues/26606), [#27359](https://github.com/cypress-io/cypress/issues/27359), [#27450](https://github.com/cypress-io/cypress/issues/27450), [#28442](https://github.com/cypress-io/cypress/issues/28442), [#30318](https://github.com/cypress-io/cypress/issues/30318), [#30718](https://github.com/cypress-io/cypress/issues/30718), [#30907](https://github.com/cypress-io/cypress/issues/30907), [#30915](https://github.com/cypress-io/cypress/issues/30915), [#30925](https://github.com/cypress-io/cypress/issues/30925), [#30954](https://github.com/cypress-io/cypress/issues/30954) and [#31185](https://github.com/cypress-io/cypress/issues/31185).


Love this long list 👍🏻

AtofStryker force-pushed the feat/replace_tsnode_for_tsx_config_process branch 2 times, most recently from 463841e to 3f1487c Compare April 15, 2025 19:18

AtofStryker force-pushed the feat/replace_tsnode_for_tsx_config_process branch from 3f1487c to 3803906 Compare April 16, 2025 03:47

jennifer-shehane assigned AtofStryker Apr 16, 2025

AtofStryker force-pushed the feat/replace_tsnode_for_tsx_config_process branch from 3803906 to dd4a87b Compare April 16, 2025 15:49

AtofStryker linked an issue Apr 18, 2025 that may be closed by this pull request

feat: replace ts-node with tsx for user configuration parsing and cypress runtime #31185

Open

AtofStryker added topic: typescript Cypress 15 labels Apr 18, 2025

AtofStryker added 6 commits April 18, 2025 15:46

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

9e4b0cc

…ases

bump ubuntu images from node 18 to 20 as node 18 is not supported in …

20fb1e1

…cypress 15 and allows us to not include the 18.19.0 workaround to use --import with tsx inside the ProjectConfigIpc

fix: issues finding tsx on windows as it needs the file:// protocol a…

dd1a8b5

…s absolute drive paths are not recognized as a file protocol in the node context

make sure to filter out stack code correctly for windows

fd80e06

fix: fix flake from windows on reporter menu not expanding (unrelated…

9c0192e

… to this PR and should be merged into develop)

chore: update changelog with all issues tsx cutover closes

916a742

AtofStryker force-pushed the feat/replace_tsnode_for_tsx_config_process branch from e069098 to 916a742 Compare April 18, 2025 19:46

AtofStryker added 2 commits April 18, 2025 16:40

fix merge conflicts

f819a48

chore: add regression tests for cypress projects that previously did …

3dfeeb9

…not work but now do with tsx

AtofStryker mentioned this pull request Apr 21, 2025

chore: update typescript docs to tsx cypress-io/cypress-documentation#6155

Merged

build all binaries

07cda56

AtofStryker changed the title ~~feat: (DRAFT) replace tsnode with tsx for parsing user configuration~~ feat: replace tsn-ode with tsx for parsing user configuration Apr 21, 2025

AtofStryker changed the title ~~feat: replace tsn-ode with tsx for parsing user configuration~~ feat: replace ts-node with tsx for parsing user configuration Apr 21, 2025

Merge branch 'release/15.0.0' of github.com:cypress-io/cypress into f…

7670fed

…eat/replace_tsnode_for_tsx_config_process

AtofStryker added the type: feature New feature that does not currently exist label Apr 23, 2025

jennifer-shehane previously requested changes Apr 23, 2025

View reviewed changes

AtofStryker added 3 commits April 24, 2025 12:30

Merge branch 'release/15.0.0' of github.com:cypress-io/cypress into f…

0669f9c

…eat/replace_tsnode_for_tsx_config_process

chore: address issues from code review

4f0a50f

update changelog

96dd554

AtofStryker requested a review from jennifer-shehane April 24, 2025 16:40

AtofStryker added 3 commits April 24, 2025 15:59

Merge branch 'release/15.0.0' into feat/replace_tsnode_for_tsx_config…

b6c3daa

…_process

remove todo comment on testing legacy migration with tsx

a05ab24

Merge branch 'feat/replace_tsnode_for_tsx_config_process' of github.c…

faad0b0

…om:cypress-io/cypress into feat/replace_tsnode_for_tsx_config_process

AtofStryker mentioned this pull request Apr 25, 2025

Overriding tsconfig.json path #23045

Open

AtofStryker commented Apr 25, 2025

View reviewed changes

packages/server/lib/plugins/child/run_require_async_child.js Outdated Show resolved Hide resolved

AtofStryker commented Apr 25, 2025

View reviewed changes

packages/server/lib/plugins/child/run_require_async_child.js Outdated Show resolved Hide resolved

AtofStryker commented Apr 25, 2025

View reviewed changes

packages/data-context/test/unit/data/ProjectConfigIpc.spec.ts Outdated Show resolved Hide resolved

AtofStryker commented Apr 25, 2025

View reviewed changes

AtofStryker added 2 commits April 28, 2025 10:49

refactor codeFrame calculation into a util function and add a unit test

7dd5ed6

updated node versions in project config ipc tests to remove 18 and te…

0a526aa

…st threshold / latest values. Removed redundant comments on ts-node.

cacieprins approved these changes Apr 28, 2025

View reviewed changes

ryanthemanuel reviewed Apr 29, 2025

View reviewed changes

ryanthemanuel approved these changes Apr 29, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: replace `ts-node` with `tsx` for parsing user configuration #31520

feat: replace `ts-node` with `tsx` for parsing user configuration #31520

AtofStryker commented Apr 15, 2025 •

edited

Loading

cypress bot commented Apr 15, 2025 •

edited

Loading

jennifer-shehane Apr 23, 2025

AtofStryker Apr 24, 2025

AtofStryker Apr 24, 2025 •

edited

Loading

jennifer-shehane Apr 23, 2025

AtofStryker Apr 24, 2025

AtofStryker Apr 25, 2025

AtofStryker Apr 28, 2025

AtofStryker Apr 25, 2025

ryanthemanuel Apr 29, 2025

		import type { DataContext } from '..'

		const tsxCodeFrameFilter = '/node_modules/tsx/dist/register'

feat: replace ts-node with tsx for parsing user configuration #31520

Are you sure you want to change the base?

feat: replace ts-node with tsx for parsing user configuration #31520

Conversation

AtofStryker commented Apr 15, 2025 • edited Loading

Closes

Side effect of not using Node as the loader

Additional details

Steps to test

How has the user experience changed?

PR Tasks

cypress bot commented Apr 15, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AtofStryker Apr 24, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

feat: replace `ts-node` with `tsx` for parsing user configuration #31520

feat: replace `ts-node` with `tsx` for parsing user configuration #31520

AtofStryker commented Apr 15, 2025 •

edited

Loading

cypress bot commented Apr 15, 2025 •

edited

Loading

AtofStryker Apr 24, 2025 •

edited

Loading