OrchardCMS/OrchardCore · error · Error

jQuery requires a window with a document

Error message

jQuery requires a window with a document

What it means

When jQuery is loaded in a CommonJS/Node-like environment without a global document, module.exports is a factory function that requires a window argument; if that window lacks a document, jQuery throws this Error instead of initializing. It prevents jQuery from running in environments with no DOM.

Solutions

  1. Ensure jQuery runs in a browser environment where window.document exists
  2. In Node tests, initialize a jsdom window first: const { JSDOM } = require('jsdom'); const { window } = new JSDOM(''); const $ = require('jquery')(window);
  3. Exclude jquery from SSR bundles or import it only inside client-only code (e.g. useEffect / onMounted)
  4. If loading via bundler config, mark jquery as external or browser-only

Example fix

// before (Node SSR)
import $ from 'jquery';
// after
import { JSDOM } from 'jsdom';
const { window } = new JSDOM('<html></html>');
const $ = require('jquery')(window);
Defensive patterns

Strategy: type-guard

Validate before calling

if (typeof document === 'undefined') { throw new Error('jQuery requires a browser DOM environment'); }

Type guard

function hasDocument(w) { return !!w && typeof w.document !== 'undefined' && w.document !== null; }

Try / catch

try { const $ = require('jquery')(someWindow); } catch (e) { if (e.message.includes('window with a document')) { // provide jsdom window or skip client-only path } }

Prevention

When it happens

Trigger: Requiring/importing jquery.js in Node.js, a web worker, SSR, or a headless context without passing a window object that has a document, e.g. require('jquery') without jsdom, or calling the returned factory with `{}`.

Common situations: Server-side rendering scripts importing jQuery; unit tests in Node without jsdom; script execution order where jQuery loads before a DOM exists; accidental CommonJS interpretation of the script in a bundler.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

AI-assisted analysis of OrchardCMS/OrchardCore@4306c0717f (2026-09-13). Data as JSON: /api/errors/c5017f139ba8eeba. Report an issue: GitHub.

Appendix: source

Thrown at src/OrchardCore.Modules/OrchardCore.Resources/wwwroot/Vendor/jquery-3.4.1/jquery.js:31

 */
( function( global, factory ) {

	"use strict";

	if ( typeof module === "object" && typeof module.exports === "object" ) {

		// For CommonJS and CommonJS-like environments where a proper `window`
		// is present, execute the factory and get jQuery.
		// For environments that do not have a `window` with a `document`
		// (such as Node.js), expose a factory as module.exports.
		// This accentuates the need for the creation of a real `window`.
		// e.g. var jQuery = require("jquery")(window);
		// See ticket #14549 for more info.
		module.exports = global.document ?
			factory( global, true ) :
			function( w ) {
				if ( !w.document ) {
					throw new Error( "jQuery requires a window with a document" );
				}
				return factory( w );
			};
	} else {
		factory( global );
	}

// Pass this if window is not defined yet
} )( typeof window !== "undefined" ? window : this, function( window, noGlobal ) {

// Edge <= 12 - 13+, Firefox <=18 - 45+, IE 10 - 11, Safari 5.1 - 9+, iOS 6 - 9.1
// throw exceptions when non-strict code (e.g., ASP.NET 4.5) accesses strict mode
// arguments.callee.caller (trac-13335). But as of jQuery 3.0 (2016), strict mode should be common
// enough that all such attempts are guarded in a try block.
"use strict";

var arr = [];

View on GitHub (pinned to 4306c0717f)