Novadesk Docs

Appearance

app ​

Control the Novadesk runtime, manage settings and logging preferences, query paths, and persist widget state across sessions.

javascript
import { app } from 'novadesk';

Availability

Available in the Main script only.

Table of Contents ​

Lifecycle ​

app.reload() #
app

Reloads all active widget scripts. Equivalent to app.refresh().

javascript
app.reload();
app.refresh() #
app

Alias of app.reload(). Reloads all active widget scripts.

javascript
app.refresh();
app.exit() #
app

Exits the Novadesk application gracefully.

javascript
app.exit();
app.beginWindowBatch() #
app

Begins a window visibility batch. All subsequent show() and hide() calls on widget windows are deferred until app.endWindowBatch() is called. Use this to prevent visual flicker when toggling multiple windows at once.

TIP

Always pair beginWindowBatch() with endWindowBatch(). Forgetting to call endWindowBatch() will leave all windows frozen in their current visibility state.

javascript
app.beginWindowBatch();
win1.show();
win2.hide();
win3.show();
app.endWindowBatch(); // all changes applied atomically
app.endWindowBatch() #
app

Ends a window visibility batch started by app.beginWindowBatch() and flushes all deferred show/hide operations.

javascript
app.beginWindowBatch();
win1.show();
win2.hide();
app.endWindowBatch();
app.requestSingleInstanceLock() #
app

Attempts to acquire the global single-instance mutex. Returns true on success. If another Novadesk instance already holds the lock, returns false. Use this when building standalone launcher widgets that should only run once.

RETURNS: boolean true if the single-instance lock was acquired, false if another instance already holds it.
javascript
const hasLock = app.requestSingleInstanceLock();
if (!hasLock) {
  console.log("Another instance is already running");
  app.exit();
}
app.releaseSingleInstanceLock() #
app

Releases the single-instance lock acquired by app.requestSingleInstanceLock().

RETURNS: boolean Always returns true.
javascript
app.releaseSingleInstanceLock();
app.isFirstRun() #
app

Returns whether this is the first time Novadesk has been launched. Useful for showing onboarding UI or setting initial defaults.

RETURNS: boolean true on the first launch when no settings file exists, false on subsequent launches.
javascript
if (app.isFirstRun()) {
  console.log("Welcome! Running for the first time.");
  app.storage.set("ui.theme", "dark");
}

Settings and Logging ​

For a full explanation of how these settings interact, see the Logging page.

app.enableDebugging(enable) #
app

Sets the global log level. When true, console.debug() output becomes visible in the log and console. Persisted to settings.json.

PARAMETERS

enable boolean
true to enable debug-level logging so console.debug() output becomes visible. false reverts to standard Info-level logging.
javascript
app.enableDebugging(true);
console.debug("Diagnostic info now visible");
app.disableLogging(disable) #
app

Completely suppresses all logging output when true. Both console and file output are stopped. Persisted to settings.json.

PARAMETERS

disable boolean
true to silence all log output (console and file). false resumes logging.
javascript
app.disableLogging(true);  // silence everything in production
app.saveLogToFile(enable) #
app

Enables or disables persistent log file output. When true, logs are appended to logs.log in the AppData directory. Persisted to settings.json.

PARAMETERS

enable boolean
true to append log output to logs.log in the AppData directory. false stops file logging.
javascript
app.saveLogToFile(true);
console.log("Log path:", app.getLogPath());
app.useHardwareAcceleration(enable) #
app

Enables or disables Direct2D hardware acceleration. Persisted to settings.json.

Requires restart

This setting is saved immediately but only takes effect after restarting Novadesk.

PARAMETERS

enable boolean
true to use Direct2D hardware rendering (default). false uses software rendering.
javascript
app.useHardwareAcceleration(false); // switch to software rendering

Paths and Version ​

app.getAppDataPath() #
app

Returns the path to the Novadesk AppData folder used for settings, logs, and storage. In portable mode this is the executable directory. Otherwise it is %APPDATA%\Novadesk\.

RETURNS: string Absolute path to the Novadesk AppData directory, ending with a path separator.
javascript
console.log(app.getAppDataPath());
// "C:/Users/Me/AppData/Roaming/Novadesk/"
app.getSettingsFilePath() #
app

Returns the full path to the Novadesk settings file.

RETURNS: string Absolute path to the active settings.json file.
javascript
console.log(app.getSettingsFilePath());
app.getLogPath() #
app

Returns the path to the current log file. Only non-empty when app.saveLogToFile(true) has been called or the saveLogToFile setting is enabled.

RETURNS: string Absolute path to logs.log if file logging is enabled, or an empty string if it is not.
javascript
const logPath = app.getLogPath();
if (logPath) {
  console.log("Logging to:", logPath);
}
app.isPortable() #
app

Returns whether Novadesk is running in portable mode. Portable mode is detected at runtime based on whether the executable directory is writable and is not a system directory.

RETURNS: boolean true when running in portable mode, false otherwise.
javascript
if (app.isPortable()) {
  console.log("Portable mode — data stored next to the exe");
}
app.getProductVersion() #
app

Returns the product version. For widgets packaged with nwm, this reports the version from meta.json.

RETURNS: string The product version string from the executable's version resources.
javascript
console.log("Version:", app.getProductVersion()); // e.g. "1.2.0.0"
app.getFileVersion() #
app

Returns the file version from the executable. For nwm-packaged widgets, this reports the value from meta.json.

RETURNS: string The file version string from the executable's version resources.
javascript
console.log("File version:", app.getFileVersion());
app.getNovadeskVersion() #
app

Returns the Novadesk engine version. This is always the engine version, even inside nwm-packaged widgets where getProductVersion() would return the widget's own version.

RETURNS: string The hardcoded Novadesk engine version string.
javascript
console.log("Engine:", app.getNovadeskVersion()); // e.g. "0.9.9.0"

Command-Line Arguments ​

app.argv and app.rawArgv are static array properties set at startup. They are not functions — read them directly as arrays.

app.argv #
app

An array of filtered command-line arguments. Internal Novadesk flags (e.g. --single-instance, --portable) are stripped. The array contains: the executable path, the entry script path, and any user-supplied arguments.

This is the recommended array to read when your widget accepts custom arguments.

javascript
// Launch: novadesk.exe index.js --theme dark --port 3000
console.log(app.argv);
// ["C:/path/to/novadesk.exe", "index.js", "--theme", "dark", "--port", "3000"]

const args = app.argv.slice(2); // user args only
app.rawArgv #
app

An array of all raw command-line arguments exactly as passed to the process, including internal Novadesk flags. Use app.argv for user-facing argument parsing.

javascript
console.log(app.rawArgv);
// ["C:/path/to/novadesk.exe", "index.js", "--single-instance", "--theme", "dark"]

Storage ​

app.storage is a simple persistent key/value store. Values are JSON-serialized and saved to storage.json in the AppData directory. Keys are strings; values can be any JSON-serializable type.

Read-modify-write on every call

Each set and remove call reads the full storage.json file, applies the change in memory, and writes the entire file back. For high-frequency updates, batch changes or use the fs module to manage your own storage file.

app.storage.get(key [, defaultValue]) #
storage

Reads a value from persistent storage. Loads the storage file fresh on every call.

PARAMETERS

key string
Storage key to read. Throws TypeError if not a string.
defaultValue any OPTIONAL
Returned when the key does not exist. Defaults to undefined.
RETURNS: any The stored value if the key exists, otherwise defaultValue or undefined.
javascript
const theme = app.storage.get("ui.theme", "dark");
const count = app.storage.get("session.count", 0);
const profile = app.storage.get("profile"); // undefined if not set
app.storage.set(key, value) #
storage

Writes a value to persistent storage. Creates the storage file if it does not exist.

PARAMETERS

key string
Storage key to write. Throws TypeError if not a string.
value any
JSON-serializable value to store. Overwrites any existing value at this key.
RETURNS: boolean true if the value was saved successfully, false if the file could not be written.
javascript
app.storage.set("ui.theme", "dark");
app.storage.set("profile", { name: "Alice", pro: true });
app.storage.set("session.count", 42);
app.storage.remove(key) #
storage

Deletes a key from persistent storage.

PARAMETERS

key string
Storage key to delete. Throws TypeError if not a string.
RETURNS: boolean true if the key existed and was removed and the file was saved successfully. false if the key was not found or the file could not be written.
javascript
const removed = app.storage.remove("session.count");
if (!removed) {
  console.log("Key did not exist");
}