Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

jQuery throws 'requires a window with a document' in Node.js

ErrorError: jQuery requires a window with a document

Short answer

jQuery needs a DOM window. A Node.js process has none, so jQuery either returns a factory function (jQuery 3) or throws on load (jQuery 4). Create a window with jsdom and pass it to jQuery: require('jquery')(window) in jQuery 3, the jquery/factory entry in jQuery 4. In Jest, switch the test environment to jsdom instead.

  • Applies to jQuery 3.7, jQuery 4.0, jsdom, Jest, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check which jQuery version is installed and which files load it. The fix differs between jQuery 3 and jQuery 4.

    grep '"version"' node_modules/jquery/package.json
    grep -rn "jquery" src/ --include=*.js
  2. 2Match what you see, then jump to its fix

    1. 1The version is 3.x and the error appears when you call $(...), not when you require jquery.jQuery 3 loaded in Node.js without a windowFix
    2. 2The version is 4.x and the error appears at the line that requires or imports jquery.jQuery 4 throws when you require it in Node.jsFix
    3. 3The error comes from a test file, and your jest config has no testEnvironment (or sets node).Jest runs the test in its default node environmentFix

What does the error look like?

  • Error: jQuery requires a window with a document
  • Uncaught Error: jQuery requires a window with a document

Cause 1 of 3

jQuery 3 loaded in Node.js without a window

1Check

In jQuery 3, when no global document exists, module.exports is a function that expects a window. Calling it with a selector string passes that string as the window, finds no document on it and throws.

grep -rn "require('jquery')" src/

2Fix

Create a window with jsdom, pass it to the function that require('jquery') returns, and use the result as your $.

npm install jsdom

// jquery-node.js
const { JSDOM } = require('jsdom');
const { window } = new JSDOM('');
const $ = require('jquery')(window);
module.exports = $;

3Verify

Run one selector against a small HTML string and print the result.

node -e "const { JSDOM } = require('jsdom'); const { window } = new JSDOM('<p id=a>hi</p>'); const \$ = require('jquery')(window); console.log(\$('#a').text())"

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 2 of 3

jQuery 4 throws when you require it in Node.js

1Check

The jQuery 4 wrapper runs the factory as soon as the module loads, and the factory throws if there is no document. For Node.js without a global window, jQuery 4 ships a separate entry point, jquery/factory (and jquery/factory-slim for the slim build).

grep -n "factory" node_modules/jquery/package.json

2Fix

Import jQueryFactory from jquery/factory and call it with a jsdom window.

// CommonJS
const { JSDOM } = require('jsdom');
const { window } = new JSDOM('');
const { jQueryFactory } = require('jquery/factory');
const $ = jQueryFactory(window);

// ES modules
import { JSDOM } from 'jsdom';
import { jQueryFactory } from 'jquery/factory';
const { window } = new JSDOM('');
const $ = jQueryFactory(window);

3Verify

Load the module and print a value read through $.

node -e "const { JSDOM } = require('jsdom'); const { window } = new JSDOM('<p id=a>hi</p>'); const { jQueryFactory } = require('jquery/factory'); console.log(jQueryFactory(window)('#a').text())"

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 3 of 3

Jest runs the test in its default node environment

1Check

Jest's default testEnvironment is node, which has no window or document. The jsdom environment provides them.

grep -rn "testEnvironment" jest.config.* package.json

2Fix

Install the jsdom environment package and select it in the Jest config, or for one file with a docblock at the top. With the global document available, require('jquery') then works as in a browser.

npm install --save-dev jest-environment-jsdom

// jest.config.js
module.exports = {
  testEnvironment: 'jsdom',
};

// or at the top of one test file
/**
 * @jest-environment jsdom
 */

3Verify

Run the failing test file again.

npx jest path/to/failing.test.js

Confirmed by jestjs.io

Did this fix it?

How do I stop it coming back?

  • Keep jQuery code in browser-only files, and put server-side logic in modules that never import jquery.
  • If you scrape or transform HTML in Node.js, create one jsdom window per document and pass it to jQuery, instead of sharing one global $.
  • Pin the jQuery major version in package.json, so a jQuery 3 to 4 upgrade is a deliberate change with a changed import.
  • Set testEnvironment per project (or per file) in Jest so browser code never runs in the node environment by accident.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.