# How to Set Up Cypress for a Node.js Project: Complete Installation Guide

> Easily set up Cypress for your Node.js project. Follow our complete guide to install, configure, write, and run your end-to-end tests efficiently.

- Repository: [Cypress.io/cypress](https://github.com/cypress-io/cypress)
- Tags: how-to-guide
- Published: 2026-06-18

---

**Install Cypress as a dev dependency using npm, Yarn, or pnpm, then run `npx cypress open` to scaffold the `cypress/` directory and configuration file, write tests in `cypress/e2e/` with [`.cy.js`](https://github.com/cypress-io/cypress/blob/main/.cy.js) extensions, and execute them via `cypress run` for CI or `cypress open` for development.**

Cypress is a fast, reliable end-to-end testing framework that runs in the browser. Setting up Cypress in a Node.js project involves installing the binary, initializing the project structure, and configuring npm scripts for interactive and headless execution. According to the cypress-io/cypress source code, the installation process documented in [`/blob/develop/README.md`](https://github.com/cypress-io/cypress/blob/main//blob/develop/README.md) supports multiple package managers and automatically generates the necessary configuration files on first run.

## Verify Node.js Version Compatibility

Before installation, ensure your Node.js environment matches the version pinned by the Cypress team. The repository includes a `.node-version` file in the root directory that specifies the exact version used for development and testing. Using this version prevents subtle incompatibilities with the Cypress binary.

## Install Cypress as a Dev Dependency

The official README at [`/blob/develop/README.md`](https://github.com/cypress-io/cypress/blob/main//blob/develop/README.md) provides installation commands for three package managers. Choose the command that matches your toolchain:

- **npm**: `npm install cypress --save-dev`
- **Yarn**: `yarn add cypress --dev`
- **pnpm**: `pnpm add cypress --save-dev`

These commands add the `cypress` package to your [`package.json`](https://github.com/cypress-io/cypress/blob/main/package.json) dependencies and download the platform-specific binary to your local `node_modules` directory.

## Initialize the Project Structure

Run the following command to scaffold the default Cypress folder structure:

```bash
npx cypress open

```

This command, implemented in the CLI package documented at [`/blob/develop/cli/README.md`](https://github.com/cypress-io/cypress/blob/main//blob/develop/cli/README.md), automatically creates:

- A `cypress.config.{js|ts}` file in your project root
- A `cypress/` directory containing `e2e/`, `fixtures/`, and `support/` folders
- Example spec files in `cypress/e2e/` to demonstrate testing patterns

## Configure npm Scripts

Add scripts to your [`package.json`](https://github.com/cypress-io/cypress/blob/main/package.json) to standardize execution across development and CI environments:

```json
{
  "scripts": {
    "cypress:open": "cypress open",
    "cypress:run": "cypress run"
  }
}

```

The `cypress:open` command launches the interactive Test Runner GUI, while `cypress:run` executes tests headlessly in the terminal, returning a non-zero exit code on failure for CI integration.

## Write Your First Test

Create test files in the `cypress/e2e/` directory using the `.cy.{js,jsx,ts,tsx}` extension. Cypress automatically discovers these files during test execution. A minimal example:

```javascript
describe('My first Cypress test', () => {
  it('loads the home page', () => {
    cy.visit('https://example.com')
    cy.contains('Example Domain')
  })
})

```

## Execute Tests

You can run tests in two modes depending on your workflow:

**Interactive Mode**: Run `npm run cypress:open` to launch the graphical interface where you can select individual specs and debug tests in real-time.

**Headless CI Mode**: Run `npm run cypress:run` for continuous integration pipelines. This mode runs all specs in the terminal without launching a browser window, making it suitable for automated testing environments.

## Customize Configuration

The generated `cypress.config.{js|ts}` file is a standard JavaScript or TypeScript module that exports a configuration object. You can customize properties such as the `baseUrl`, test file patterns, retry logic, and enable component testing mode. The configuration schema is documented in the official Cypress documentation and referenced in the repository's example configuration files.

## Summary

- Check the `.node-version` file in the cypress-io/cypress repository to ensure Node.js compatibility
- Install via `npm install cypress --save-dev`, `yarn add cypress --dev`, or `pnpm add cypress --save-dev` as shown in [`/blob/develop/README.md`](https://github.com/cypress-io/cypress/blob/main//blob/develop/README.md)
- Scaffold the project with `npx cypress open` to create `cypress.config.{js|ts}` and the `cypress/` directory structure
- Add `cypress:open` and `cypress:run` scripts to [`package.json`](https://github.com/cypress-io/cypress/blob/main/package.json) for convenient execution
- Write tests using `.cy.{js,ts}` extensions in the `cypress/e2e/` directory
- Use `cypress open` for development and `cypress run` for CI pipelines

## Frequently Asked Questions

### What Node.js version does Cypress require?

The cypress-io/cypress repository maintains a `.node-version` file in the root directory that pins the exact version used by the core team. Matching this version ensures compatibility with the Cypress binary and avoids subtle runtime errors during test execution.

### Can I use TypeScript with Cypress?

Yes. Cypress natively supports TypeScript. When you run `npx cypress open`, the scaffolding process can generate [`cypress.config.ts`](https://github.com/cypress-io/cypress/blob/main/cypress.config.ts) instead of `.js`, and test files can use [`.cy.ts`](https://github.com/cypress-io/cypress/blob/main/.cy.ts) or [`.cy.tsx`](https://github.com/cypress-io/cypress/blob/main/.cy.tsx) extensions. The configuration loader automatically handles TypeScript compilation without additional setup.

### How do I run Cypress tests in CI without the GUI?

Use the `cypress run` command, typically accessed via `npm run cypress:run` if you configured the package.json script. This headless mode, documented in [`/blob/develop/cli/README.md`](https://github.com/cypress-io/cypress/blob/main//blob/develop/cli/README.md), executes all specs in the terminal and exits with a non-zero status code on failure, which is essential for CI pipelines like GitHub Actions or Jenkins.

### Where should I store my test files?

Store end-to-end tests in the `cypress/e2e/` directory using files ending in `.cy.{js,jsx,ts,tsx}`. According to the source code structure, Cypress automatically discovers and loads these files during test execution, organizing them in the Test Runner interface based on this directory pattern.