Cypress tsconfig.json configuration with "type": "module"?

[MikeMcC399]

Description

What would you like?

Document how to set up Cypress with TypeScript when package.json contains "type": "module".

Why is this needed?

Tooling > TypeScript states that Cypress tests can be written in TypeScript and includes a section Configure tsconfig.json.

The Node.js type field in package.json can be defined as module, commonjs or left undefined. If the field type is defined as module, then .js files are treated as CommonJS.

Other

According to https://www.typescriptlang.org/docs/handbook/modules/reference.html#the-module-compiler-option

node16 and nodenext are the only correct module options for all apps and libraries that are intended to run in Node.js v12 or later, whether they use ES modules or not.

Using the following in tsconfig.json appears to work

"compilerOptions": {
"module": "nodenext" /* Specify what module code is generated. */
}

however I don't have experience in TypeScript to want to be the author of a documentation change.

• Also Typescript for >=v10 #5262 is still open and waiting for an experienced TypeScript user to update the documentation to cover Cypress non-legacy (Cypress 10 and above) use with TypeScript.

[MikeMcC399]

For comparison, when scaffolding Vite 6, it sets up tsconfig.json with the following, and it runs out-of-the-box

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "module": "ESNext",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "skipLibCheck": true,

    /* Bundler mode */
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "isolatedModules": true,
    "moduleDetection": "force",
    "noEmit": true,

    /* Linting */
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedSideEffectImports": true
  },
  "include": ["src"]
}

Versions

Component	Version
Ubuntu	24.04.1 LTS
Node.js	v22.13.0 LTS
Cypress	13.17.0
TypeScript	5.6.3
create-vite	6.1.1
vite	6.0.7

Steps

npm create vite@latest vite-cypress-ts -- --template vanilla-ts
cd vite-cypress-ts
npm install cypress -D
npx cypress open

Select "Continue" (if prompted)
Select "E2E Testing"
Select "Continue"
Select "Electron" and then "Start E2E Testing in Electron"
Select "Create new spec"
Select "Create spec"
Select "Okay, run the spec"

Close all Cypress windows

npx cypress run

[MikeMcC399]

• See also issue TypeScript and package.json type module (ESM) shows "ExperimentalWarning: --experimental-loader" cypress#30318