Environment:Nightwatchjs Nightwatch Node 18 Runtime

Knowledge Sources	Nightwatch.js Node.js Releases
Domains	Infrastructure, Runtime
Last Updated	2026-02-12 01:00 GMT

Overview

Node.js >= 18.20.5 runtime environment required for running Nightwatch.js v3.15.0 test framework.

Description

Nightwatch.js requires a minimum Node.js version of 18.20.5 (LTS). This constraint is enforced at startup via a semver check in the CLI entry point. The framework relies on modern Node.js features including native ES module support via dynamic `import()`, the `node:url` built-in module, and DNS resolution ordering APIs introduced in Node.js v17+. The runtime must support CommonJS modules as the primary module system, with ESM support available through dynamic imports.

Usage

This environment is mandatory for all Nightwatch.js operations. Every CLI invocation (`npx nightwatch`) and programmatic usage (`require('nightwatch')`) requires this Node.js version. The version check runs before any test code executes, and the process exits with an error if the requirement is not met.

System Requirements

Category	Requirement	Notes
OS	Linux, macOS, Windows	Cross-platform Node.js support
Runtime	Node.js >= 18.20.5	LTS version required; enforced at startup
Package Manager	npm >= 8.x or compatible	For installing Nightwatch and dependencies
Disk	~50MB for node_modules	Nightwatch core plus selenium-webdriver

Dependencies

System Packages

`node` >= 18.20.5 (LTS)
`npm` >= 8.x (bundled with Node.js 18)

Node.js Packages (Core)

`selenium-webdriver` = 4.27.0
`semver` = 7.5.4
`dotenv` = 16.3.1
`mocha` = 10.8.2
`lodash` >= 4.17.21
`jsdom` >= 24.1.0
`piscina` >= 4.3.1

Optional Packages

`chromedriver` (optional peer dependency for local Chrome testing)
`geckodriver` (optional peer dependency for local Firefox testing)
`@cucumber/cucumber` >= 8.2.1 (optional peer dependency for BDD tests)
`@nightwatch/mobile-helper` (optional, for Android/iOS mobile testing)
`ts-node` (optional, for TypeScript test file support)

Credentials

No credentials are required for the base Node.js runtime environment.

The following optional environment variables affect runtime behavior:

`COLORS`: Set to `'0'` to disable colored terminal output.
`NIGHTWATCH_RERUN_REPORT_FILE`: Path to a JSON file for tracking test rerun state.
`NIGHTWATCH_RERUN_FAILED`: Set to `'1'` to rerun only previously failed tests.

Quick Install

# Install Node.js 18 LTS (via nvm)
nvm install 18
nvm use 18

# Verify version
node --version  # must be >= 18.20.5

# Install Nightwatch
npm init nightwatch@latest

# Or add to existing project
npm install nightwatch --save-dev

Code Evidence

Node.js version enforcement from `bin/nightwatch:3-16`:

const semver = require('semver');
const {Logger} = require('../lib/utils');
const requiredVersion = require('../package.json').engines.node;

function checkNodeVersion (wanted, id) {
  if (!semver.satisfies(process.version, wanted)) {
    Logger.error('You are using Node ' + process.version + ', but this version of ' + id +
      ' requires Node ' + wanted + '.\nPlease upgrade your Node version.'
    );
    process.exit(1);
  }
}

checkNodeVersion(requiredVersion, 'nightwatch');

Engine constraint from `package.json:128-130`:

"engines": {
  "node": ">= 18.20.5"
}

ESM/CommonJS module handling from `lib/utils/requireModule.js:18-46`:

module.exports = function (fullpath) {
  let exported;
  try {
    exported = require(fullpath);
  } catch (err) {
    const isEsmSyntaxError = err.message === 'Cannot use import statement outside a module' ||
      err.message.includes('Unexpected token \'export\'');
    const isMjsFile = fullpath.endsWith('.mjs');

    if (err.code === 'ERR_REQUIRE_ESM' || (isMjsFile && isEsmSyntaxError)) {
      const { pathToFileURL } = require('node:url');
      return import(pathToFileURL(fullpath).href).then(mergeDefaultAndNamedExports);
    }
    // ...
  }
}

Common Errors

Error Message	Cause	Solution
`You are using Node vX.X.X, but this version of nightwatch requires Node >= 18.20.5`	Node.js version too old	Upgrade Node.js: `nvm install 18`
`Cannot use import statement outside a module`	ES module syntax in CommonJS context	Add `"type": "module"` to package.json or use `.mjs` extension
`ERR_REQUIRE_ESM`	Requiring an ESM-only module	Nightwatch handles this automatically via dynamic `import()`; ensure Node.js >= 18
`@nightwatch/mobile-helper needs to be installed as a project dependency`	Missing optional mobile helper package	`npm i @nightwatch/mobile-helper --save-dev`

Compatibility Notes

Node.js 18.x (LTS): Fully supported. Minimum version 18.20.5 required.
Node.js 20.x (LTS): Fully supported. Improved ESM `require()` support for `.mjs` files.
Node.js 17+: DNS resolution defaults changed; Nightwatch applies `dns.setDefaultResultOrder('ipv4first')` workaround automatically.
Node.js < 18: Not supported. Process exits immediately with version mismatch error.
TypeScript: Supported via `ts-node` with `transpileOnly: true`. Nightwatch auto-detects `nightwatch/tsconfig.json` or `tsconfig.nightwatch.json`.
Windows: Fully supported via Node.js cross-platform runtime.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment