Windows & macOS apps — Noderyx Documentation

01

One view, three places

The desktop app ships the same compiled bundle as the packaged mobile build: clean routes, .mnoderframe pages, Cool.css, and the Noderyx.native bridge. Electron draws the window and electron-builder packages it.

TERMINAL

npm run desktop:init     # compile views, install Electron
npm run desktop:run      # open the app in a window
npm run desktop:windows  # platforms/desktop/dist/*.exe

Note

Electron and electron-builder install inside platforms/desktop. Your web app's dependencies—and your server—stay small.

02

Requirements

Node.js 20 or later, plus the operating system you are packaging for.

Windows installer (.exe) Build on Windows. macOS and Linux can too, with Wine installed.

macOS disk image (.dmg) Build on a Mac. Apple only allows macOS apps to be built and signed on macOS.

Linux AppImage Build on Linux.

Note

On Windows and need a Mac build? Use the GitHub Actions workflow below.

03

Everyday commands

Every command rebuilds from your views first, so you never package stale pages.

TERMINAL

noderyx desktop:run                  # build and open in a window
noderyx desktop:package windows      # .exe installer
noderyx desktop:package mac          # .dmg and .zip, on a Mac
noderyx desktop:package linux        # AppImage
noderyx build:desktop                # rebuild the bundle only

04

Develop against the live server

Point the window at your dev server to see changes without rebuilding.

TERMINAL

npm run dev                                              # terminal one
noderyx desktop:run --live-reload=http://localhost:3000  # terminal two

05

Configuration

Add a desktop block to noderyx.config.js. Anything it leaves out—appId, appName, views, entry, apiUrl, data, pages—comes from your mobile block, so most projects only set the window.

noderyx.config.js

desktop: {
  appId: "com.example.myapp",
  appName: "My App",
  apiUrl: process.env.DESKTOP_API_URL ?? null,
  window: { width: 1200, height: 800, minWidth: 720, minHeight: 480, rememberBounds: true },
  singleInstance: true,
  permissions: ["notifications", "clipboard-sanitized-write", "fullscreen"],
  windows: { targets: ["nsis"] },
  mac: { targets: ["dmg", "zip"] }
}

Note

DESKTOP_APP_ID and DESKTOP_API_URL override the config, and fall back to the MOBILE_ values when empty.

06

Talking to your server

The desktop app has no server of its own. Its pages are served from the private origin noderyx://app, so set apiUrl to your deployed Noderyx server and allow that origin.

.env

CORS_ORIGINS=noderyx://app,capacitor://localhost,https://localhost

Note

The build rewrites server routes to absolute URLs, and Noderyx.native.api("/api/...") resolves against apiUrl.

07

Detect the desktop in your pages

The bridge tells a page where it is running, and the html element gets a class and a data-platform attribute so CSS can adapt.

JAVASCRIPT

Noderyx.native.isDesktop   // true inside the desktop app
Noderyx.native.platform    // "windows", "macos", or "linux"

/* CSS */
.noderyx-desktop .mobile-only { display: none; }
[data-platform="macos"] .titlebar { padding-left: 80px; }

Note

Noderyx.native.notify() shows system notifications, and Noderyx.native.browser(url) opens links in the default browser.

08

Secure by default

The generated app follows Electron's security checklist.

Pages run sandboxed with context isolation and no Node.js access.
The bundle is served from a private, secure scheme that cannot reach files outside it.
The mobile build's Content Security Policy still applies: only bundled scripts run.
Links that leave the app open in the system browser—http, https, and mailto only.
Permission requests not listed in permissions are refused.
Developer tools are off in packaged builds unless devTools: true.

Note

main.cjs and preload.cjs are rewritten on every build so framework updates reach your app. Configure through noderyx.config.js rather than editing them.

09

Build Windows and macOS from anywhere

You cannot build a macOS app on Windows, but GitHub can. The workflow packages the installer on a Windows runner and the disk image on a macOS runner, and attaches both to the run.

TERMINAL

npx noderyx desktop:workflow # writes .github/workflows/desktop.yml

Note

Run it from the Actions tab, or push a tag such as v1.0.0.

10

Icons and code signing

Replace platforms/desktop/build/icon.png with your own 1024×1024 PNG; it becomes the .ico and .icns. Unsigned builds work, but Windows SmartScreen and macOS Gatekeeper warn users first. To sign, give electron-builder your certificates through environment variables or repository secrets.

CSC_LINK / CSC_KEY_PASSWORD Base64 .p12 or .pfx certificate and its password.

APPLE_ID / APPLE_APP_SPECIFIC_PASSWORD The Apple ID that notarizes the macOS app.

APPLE_TEAM_ID Your Apple Developer team ID.

11

What to commit

Commit platforms/desktop/package.json, its package-lock.json, and build/icon.png. The generated .gitignore already excludes www/, node_modules/, and dist/.

Note

If the window never opens and Electron prints a Node.js version, something set ELECTRON_RUN_AS_NODE=1. Noderyx clears it for desktop:run and desktop:package.