Skip to content

chore: update typescript docs to tsx #6155

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 22, 2025
Merged

chore: update typescript docs to tsx #6155

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0a5852e
chore: remove ts-node references and workarounds and replace them wit…
AtofStryker Apr 21, 2025
2b62c71
add empty changelog entry for 15 to allow for linked out changes to b…
AtofStryker Apr 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/app/references/changelog.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,10 @@ sidebar_label: Changelog

# Changelog

## 15.0.0

_Released 7/01/2025 (PENDING)_

## 14.2.1

_Released 3/26/2025_
Expand Down
37 changes: 12 additions & 25 deletions docs/app/tooling/typescript-support.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ tests in TypeScript.

### Install TypeScript

To use TypeScript with Cypress, you will need TypeScript 4.0+. If you do not
To use TypeScript with Cypress, you will need TypeScript 5.0+. If you do not
already have TypeScript installed as a part of your framework, you will need to
install it:

Expand Down Expand Up @@ -61,8 +61,8 @@ with the following configuration:
```json title="tsconfig.json"
{
"compilerOptions": {
"target": "es5",
"lib": ["es5", "dom"],
"target": "es6",
"lib": ["es6", "dom"],
"sourceMap": true,
"types": ["cypress", "node"]
},
Expand Down Expand Up @@ -94,23 +94,9 @@ If that does not work, try restarting the IDE.

### Processing your Cypress configuration and plugins

Cypress needs to be able to transpile your Cypress configuration and plugins written in TypeScript in order to make them executable within Cypress's Node.js runtime. To do this, Cypress will attempt to read the user's TypeScript and project configuration to apply the correct TypeScript loader to Cypress's Node.js runtime.
Under the hood, Cypress uses [tsx](https://tsx.is/) to parse and run the `cypress.config.ts` file.

If your project is an `ESM` package (short for [ECMAScript Module](https://nodejs.org/api/esm.html#modules-ecmascript-modules)), Cypress attempts to apply the [ts-node/esm](https://github.com/TypeStrong/ts-node?tab=readme-ov-file#esm) Node.js loader to resolve the Cypress configuration and plugins. `ESM` is determined by Cypress if you have the `type: "module"` key-value pair present inside your project's `package.json`.

Otherwise, regular [ts-node](https://github.com/TypeStrong/ts-node?tab=readme-ov-file#node-flags-and-other-tools) is required into Cypress's Node.js runtime.
Since Node.js by itself can only interpret CommonJS files, Cypress attempts to make your TypeScript configuration compatible with Cypress' Node.js runtime.
To do this, Cypress overrides the following configuration values found inside your project's `tsconfig.json`:

```json
{
"module": "commonjs",
"moduleResolution": "node",
"preserveValueImports": false
}
```

This does not have an impact on your project or its TypeScript configuration settings. This override only happens within the context of the Cypress runtime.
This allows Cypress to run your TypeScript configuration inside the Cypress runtime without being bound to limitations of Node or other loaders.

## Extending TypeScript Support

Expand Down Expand Up @@ -380,12 +366,13 @@ root `tsconfig.json` file.

## History

| Version | Changes |
| ------------------------------------------ | ------------------------------------------------------------------------------------------ |
| [13.0.0](/app/references/changelog#13-0-0) | Raised minimum required TypeScript version from 3.4+ to 4.0+ |
| [10.0.0](/app/references/changelog#10-0-0) | Update guide to cover TypeScript setup for component testing |
| [5.0.0](/app/references/changelog#5-0-0) | Raised minimum required TypeScript version from 2.9+ to 3.4+ |
| [4.4.0](/app/references/changelog#4-4-0) | Added support for TypeScript without needing your own transpilation through preprocessors. |
| Version | Changes |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| [15.0.0](/app/references/changelog#15-0-0) | Raised minimum required TypeScript version from 4.0+ to 5.0+ and replaced `ts-node` with `tsx` to parse and run the `cypress.config.ts` file. |
| [13.0.0](/app/references/changelog#13-0-0) | Raised minimum required TypeScript version from 3.4+ to 4.0+ |
| [10.0.0](/app/references/changelog#10-0-0) | Update guide to cover TypeScript setup for component testing |
| [5.0.0](/app/references/changelog#5-0-0) | Raised minimum required TypeScript version from 2.9+ to 3.4+ |
| [4.4.0](/app/references/changelog#4-4-0) | Added support for TypeScript without needing your own transpilation through preprocessors. |

## See also

Expand Down