Diagnosing Blank Windows and Missing Node APIs in NW.js

Problem and takeaway

If an NW.js window opens blank, or the renderer console throws require is not defined, process is undefined, or window.node is undefined, the application is attempting to use Node.js APIs in a renderer context that does not expose them. The useful takeaway is that these failures are usually manifest configuration issues rather than missing Node.js installations. Before reinstalling dependencies, confirm whether Node integration is enabled for the target window and whether the entry HTML matches the packaged main field.

Recognizable conditions

Look for one or more of the following symptoms at launch:

• A white or blank window with no visible UI.
• Console error require is not defined when a script calls Node built-ins or npm packages.
• Reference process or window.node is undefined in renderer code.
• Application runs during development but shows a blank window after packaging.
• Immediate crash or segmentation fault when a native module loads.

Cause and diagnostic table

Observed condition	Likely cause	First place to check
Blank window; require is not defined	nodeIntegration disabled in window manifest	package.json → window.nodeIntegration
process is undefined in renderer	Renderer running in isolated context without Node exposure	DevTools console → typeof process
Works in dev, blank after packaging	main field mismatch or entry HTML outside app root	package.json → main vs packaged file tree
Crash on native module load	Native module built for wrong Node ABI or architecture	Console module-load error; native module build logs

Ordered checks

1. Confirm the entry point and manifest

   Open package.json in the application root. Verify that main points to the HTML file that actually loads your renderer code, and that window.nodeIntegration is present under window.

   {
     "name": "diagnostic-app",
     "main": "index.html",
     "window": {
       "nodeIntegration": true
     }
   }

   Run this check in the project directory as a normal user; no elevated permissions are required. Risk: editing package.json while NW.js is running has no effect until the process restarts.

2. Probe the renderer from DevTools

   Launch the app with Developer Tools open. In the renderer console, evaluate:

   typeof require
   typeof process
   typeof window.node

   Expected results when Node integration is active: function, object, and object respectively. If any returns undefined, Node is not exposed in that context. This check requires no file changes and carries no risk.

3. Verify file paths and working directory

   Confirm that relative paths in main, preload scripts, and asset references resolve from the packaged app root, not the developer’s source directory. After packaging, inspect the extracted archive or ASAR to confirm index.html exists at the path declared in main.

4. Review console for module and ASAR errors

   Look for Cannot find module, The specified module could not be found, or ASAR path errors. Native module failures often appear before the blank window and indicate an ABI mismatch rather than a manifest issue.

Fixes tied to findings

1. Enable Node integration in the manifest

If typeof require returned undefined, set nodeIntegration to true for the relevant window and restart NW.js. Manifest changes do not apply through hot reload.

"window": {
  "nodeIntegration": true
}

Security note: enabling Node integration exposes Node.js APIs to the renderer. Do not enable it for windows that load untrusted or remote content.

2. Align the main field with the packaged entry

If main points to src/index.html but packaging copies only dist/, the renderer may fail to load. Point main to the file that exists in the final package, or adjust the packaging step to preserve the expected layout.

3. Use a preload bridge for isolated contexts

If you prefer to keep nodeIntegration disabled for security, expose only the APIs you need through a preload script. Configure the preload in window options, then use the bridge mechanism supported by your NW.js version to expose require-derived utilities to the isolated renderer. This is a version-sensitive feature; confirm the preload API against your NW.js release notes.

4. Rebuild native modules for the NW.js runtime

Native modules must match the Node.js ABI and architecture used by the NW.js version. Rebuild them against the NW.js target, not the system Node.js. Example command location and shape:

cd 
nw-gyp rebuild --target= --arch=

Run as a normal user in the app directory. Risk: rebuilding with the wrong --target or --arch produces a module that fails to load at runtime, often with a cryptic DLL or .node load error.

Escalation criteria

Escalate beyond manifest edits when:

• The application segfaults immediately on launch after manifest correction.
• A native module still fails after rebuilding for the correct NW.js ABI and architecture.
• The window remains blank after nodeIntegration is enabled and main is verified.
• Behavior differs between development and packaged builds, suggesting code signing, ASAR isolation, or platform-specific file access issues.

Limitations and verification

Manifest schema and nodeIntegration behavior differ between legacy node-webkit and current NW.js releases. Verify against the documentation for your exact NW.js version. Enabling Node integration increases the application’s attack surface; restrict it to windows that load trusted local content.

Practical check: after applying a fix, launch the app with DevTools open and re-run typeof require and typeof process in the renderer. If both return expected types and the window renders, the integration issue is resolved. For isolation, test a minimal NW.js hello-world app with the same manifest and packaging settings before concluding that application code is at fault.

Rollback

Because editing package.json changes application state, you can roll back by restoring the previous window.nodeIntegration value or removing the key, then restarting NW.js. There is no runtime rollback without a restart.