Resolving 'require is not defined' and Node API Failures in NW.js

The Problem: Missing Node.js Context in the Renderer

When developing with NW.js, a common failure occurs when the browser window (the renderer process) cannot access Node.js APIs. This typically manifests as a ReferenceError: require is not defined or nw is undefined in the DevTools console, preventing the application from accessing the file system, OS modules, or the NW.js GUI library.

Diagnostic Matrix

Use this table to match your specific symptom to the most likely architectural cause.

Symptom	Likely Cause	Diagnostic Indicator
require is not defined	Node integration disabled	package.json lacks "node-remote" or "node-integration" settings.
nw is undefined	Version mismatch or context loss	Running an outdated NW.js version or loading a remote URL without permissions.
CSP Violation Error	Restrictive Security Policy	Console shows Refused to evaluate script because it violates the following Content Security Policy...
Blank screen / No execution	Invalid Entry Point	"main" in package.json points to a non-existent or malformed HTML file.

Step-by-Step Verification Process

Perform these checks in order to isolate whether the issue is configuration-based or environment-based.

1. Check the Manifest: Open your package.json. Ensure the main property points to a local HTML file. If you are loading a remote URL, verify that node-remote is configured for that specific domain.
2. Verify Runtime Context: Launch the application and open the Chrome DevTools (F12). Type process.versions.nwjs into the console. If this returns undefined, the renderer is running as a standard web page without Node.js integration.
3. Inspect CSP Headers: Check the <meta http-equiv="Content-Security-Policy"> tag in your HTML. If it lacks script-src 'unsafe-eval', Node's internal module loading may be blocked.

Targeted Fixes

Scenario A: Node Integration is Disabled

If the renderer is treated as a standard browser window, you must explicitly enable Node integration in the package.json manifest.

{
  "name": "my-app",
  "main": "index.html",
  "window": {
    "node-remote": "<all_urls>"
  },
  "nodejs": true
}

Risk: Enabling node-remote for <all_urls> allows any website loaded in the window to execute system-level commands. Limit this to trusted domains only.

Scenario B: CSP Blocking Module Execution

Node.js integration often requires the ability to evaluate code dynamically. If your security policy is too strict, require() will fail.

Update your HTML meta tag to allow evaluation for local development:

<meta http-equiv="Content-Security-Policy" content="script-src 'self' 'unsafe-eval';">

Scenario C: API Deprecation (Legacy Versions)

If you are using a version of NW.js older than 0.12, nw.gui was the primary entry point. In modern versions, the nw object is globally available. If nw is undefined but require works, check your NW.js version via process.versions.nwjs and update to a current stable release.

Verification and Testing

To confirm the fix, run the following test in the DevTools console of your application window:

// Test 1: Node.js availability
console.log("Node Version:", process.version);

// Test 2: Module access
const fs = require('fs');
console.log("FS Module Loaded:", !!fs);

// Test 3: NW.js API access
console.log("NW Object Available:", !!nw);

The operation is successful if all three tests return true/defined without throwing a ReferenceError.

Escalation Criteria

If the above steps do not resolve the issue, escalate to a deeper architectural review if:

• The app works in a standalone browser but fails only when packaged as an NW.js binary.
• require works for built-in modules (like fs) but fails for npm modules installed in node_modules.
• The application crashes immediately upon calling a Node API, indicating a binary incompatibility between the Node.js version and the NW.js runtime.