jQuery throws 'requires a window with a document' in Node.js
Error: jQuery requires a window with a documentShort 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.
Fix it fast
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=*.js2Match what you see, then jump to its fix
- 1
The 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
The 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
The 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
- 1
What does the error look like?
Error: jQuery requires a window with a documentUncaught 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
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.json2Fix
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
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.json2Fix
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.jsConfirmed by jestjs.io
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 fixBack end
ng fails with Cannot find module @angular/cli/bin/ng
Cannot find module '@angular/cli/bin/ng'
The ng command is the entry point to the Angular CLI package.
2 causes, each with a fixBack end
Angular app shows 'Cannot GET /' when served by a Node.js server
Cannot GET /dashboard
Cannot GET / is Express saying no route or file matches the request.
3 causes, each with a fixBack 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 fixBack end
Angular build says it cannot resolve '@angular/localize/init'
Can't resolve '@angular/localize/init' in '/usr/src/app/src'
The build imports @angular/localize, and that package is not in node_modules.
2 causes, each with a fixBack end
The command npm run build -- --prod exited with code 1 (Angular)
The command "npm run build -- --prod" exited with code 1
Exit code 1 only says the build failed; the real message is above it.
2 causes, each with a fix