Windadd

Windadd is a Node.js desktop library and CLI for Windows 10/11 apps built with:

• native WinAPI windows
• WebView2 for HTML, CSS, and JavaScript

It is designed to stay simple on the JavaScript side while still talking directly to native Windows APIs.

Requirements

• Windows 10 or Windows 11
• Node.js >= 20
• x64 Node.js
• WebView2 Runtime installed

Install

npm install windadd

What Changed In 0.3.0

• the npm package no longer ships a precompiled Windadd.Host.exe
• the native host is compiled locally from native/Windadd.Host.cs
• runtime artifacts are cached in %LOCALAPPDATA%\Windadd\runtime\<packageVersion>\x64
• old generated projects can be migrated with windadd repair
• the recommended dev-server manifest format now uses serverExecutable + serverArgs

Quick Start

Create a project:

windadd start-project

Run it:

windadd run

Create a Vite + React + TypeScript project:

windadd start-project --template vite-react-ts
npm install
windadd run --dev

CLI

Create a project

windadd start-project
windadd start-project --template vite-react-ts

Repair an older generated project

windadd repair

This updates the generated src/main.js, normalizes package.json scripts, and migrates the old Vite dev command manifest when it matches the known Windadd scaffold.

Run the current project

windadd run
windadd run --dev
windadd run --url https://example.com
windadd run --file app/index.html
windadd run --entry src/main.js
windadd run --dev --verbose

Build a distributable folder

windadd compile

This produces Dist/ with:

• your project files
• a launcher .exe
• node.exe when bundleNode is enabled
• a local node_modules/windadd runtime copy

Project Files

windadd start-project creates:

• windadd-package.json
• package.json
• src/main.js
• src/preload.js
• assets/

Default template also creates:

• app/index.html

Vite template also creates:

• web/index.html
• web/src/*
• vite.config.ts
• tsconfig.json

package.json Scripts

Generated projects get:

• desktop
• desktop:dev
• desktop:build
• desktop:repair

The Vite template also adds:

• dev:web
• build:web

Manifest

windadd-package.json controls app metadata, startup paths, window defaults, rendering, development mode, and build output.

Example:

{
  "name": "Windadd Demo",
  "appId": "dev.windadd.demo",
  "version": "0.1.0",
  "entry": "src/main.js",
  "startupDirectory": ".",
  "icon": null,
  "development": {
    "serverExecutable": "npm.cmd",
    "serverArgs": ["run", "dev:web"],
    "serverUrl": "http://127.0.0.1:5173",
    "serverCwd": ".",
    "readyTimeoutMs": 30000
  },
  "window": {
    "title": "Windadd Demo",
    "width": 1280,
    "height": 820,
    "minWidth": 960,
    "minHeight": 600,
    "resizable": true,
    "center": true,
    "show": true,
    "frame": false,
    "alwaysOnTop": false,
    "roundedCorners": true,
    "cornerRadius": 18,
    "dragRegionHeight": 40,
    "backgroundColor": "#10141b",
    "devTools": true,
    "file": "web-dist/index.html"
  },
  "rendering": {
    "mode": "balanced",
    "allowCpuFallback": true,
    "backgroundInitialization": true,
    "browserArguments": []
  },
  "build": {
    "outputDirectory": "Dist",
    "include": ["src", "assets", "web-dist", "windadd-package.json"],
    "subdirectories": true,
    "clean": true,
    "bundleNode": true
  },
  "product": {
    "executableName": "Windadd Demo"
  }
}

Development Manifest

Recommended format:

{
  "development": {
    "serverExecutable": "npm.cmd",
    "serverArgs": ["run", "dev:web"],
    "serverUrl": "http://127.0.0.1:5173",
    "serverCwd": ".",
    "readyTimeoutMs": 30000
  }
}

Legacy compatibility format still supported:

{
  "development": {
    "serverCommand": "npm run dev:web",
    "serverUrl": "http://127.0.0.1:5173"
  }
}

Public API

Windadd exports:

• createApp(options)
• WindaddApp
• BrowserWindow
• WindaddError
• formatErrorReport(error)
• loadProjectManifest(startDir)
• startProject(projectDir?, options?)
• repairProject(projectDir?)
• runProject(projectDir?, options?)
• compileProject(projectDir?)

App API

const { createApp } = require('windadd');

const app = createApp({
  id: 'dev.windadd.demo',
  name: 'Windadd Demo',
  userDataDir: 'C:\\apps\\windadd-demo',
  rendering: {
    mode: 'balanced',
    allowCpuFallback: true,
    backgroundInitialization: true,
    browserArguments: [],
  },
});

App options

• id or appId
• name
• userDataDir or userDataPath
• rendering
• renderMode

App methods

• await app.whenReady()
• await app.createWindow(options)
• app.getPath('appData' | 'userData' | 'temp' | 'home')
• app.setUserDataPath(path)
• await app.quit()

App events

• ready
• before-quit
• quit
• window-created
• window-all-closed
• host-error
• host-stderr
• error

BrowserWindow API

const win = await app.createWindow({
  title: 'Main Window',
  width: 1280,
  height: 820,
  minWidth: 960,
  minHeight: 600,
  center: true,
  show: true,
  frame: false,
  roundedCorners: true,
  cornerRadius: 18,
  dragRegionHeight: 40,
  backgroundColor: '#10141b',
  devTools: true,
});

await win.loadFile('app/index.html');

Window options

• title
• width
• height
• minWidth
• minHeight
• resizable
• center
• show
• frame
• frameless
• roundedCorners
• cornerRadius
• dragRegionHeight
• alwaysOnTop
• backgroundColor
• devTools
• url
• file

Important validation

• roundedCorners: true requires frame: false or frameless: true
• cornerRadius must be at least 4
• runtime url/file overrides can come from CLI flags or the manifest

Window methods

• await win.loadURL(url)
• await win.loadFile(filePath)
• await win.show()
• await win.hide()
• await win.focus()
• await win.close()
• await win.setTitle(title)
• await win.setSize(width, height)
• await win.setPosition(x, y)
• await win.center()
• await win.minimize()
• await win.maximize()
• await win.restore()
• await win.send(channel, data)
• await win.executeJavaScript(script)
• win.handle(channel, handler)
• win.unhandle(channel)
• win.isDestroyed()

Window events

• shown
• close
• closed
• resize
• navigation-start
• navigation-complete
• dom-ready
• crash
• message

Renderer Bridge

Every loaded page receives window.windadd.

Renderer methods

• window.windadd.send(channel, data)
• window.windadd.on(channel, handler)
• window.windadd.off(channel, handler)
• window.windadd.invoke(channel, data)

Example:

<script>
  window.windadd.on('host:hello', (data) => {
    console.log(data);
  });

  async function readVersion() {
    const result = await window.windadd.invoke('system.version');
    console.log(result);
  }

  window.windadd.send('renderer:ready', {
    now: new Date().toISOString()
  });
</script>

Rendering Modes

rendering.mode supports:

• balanced
• hardware
• cpu

Additional rendering fields:

• allowCpuFallback
• backgroundInitialization
• browserArguments

Vite + React + TypeScript

Create:

windadd start-project --template vite-react-ts

Install dependencies:

npm install

Run dev mode:

windadd run --dev

Build frontend and package desktop output:

npm run build:web
windadd compile

If you created the project with an older Windadd version, run:

windadd repair

Storage and Runtime Paths

By default, Windadd writes to:

• WebView2 profile data: %APPDATA%\Windadd\apps\<appId>
• native runtime cache: %LOCALAPPDATA%\Windadd\runtime\<packageVersion>\x64
• temporary launcher source: %TEMP%\windadd-launcher-*.cs

Environment overrides:

• WINDADD_RUNTIME_DIR
• WINDADD_USER_DATA_DIR
• WINDADD_RUN_URL
• WINDADD_RUN_FILE
• WINDADD_PACKAGE_ROOT

Security and Transparency

• no preinstall, install, or postinstall scripts
• no hidden telemetry
• no automatic network requests during npm install
• no precompiled Windadd.Host.exe inside the npm tarball

Useful references:

• SECURITY.md
• VENDORED-ARTIFACTS.md

Error Reporting

Windadd returns structured errors through WindaddError and formatErrorReport(error).

Reports include:

• error code
• message
• source
• request ID when available
• window ID when available
• native details
• stack trace
• best-effort source location

Example:

try {
  await app.createWindow({
    frame: true,
    roundedCorners: true,
  });
} catch (error) {
  console.error(formatErrorReport(error));
}

Notes

• Windadd targets Windows x64.
• Live WebView2 windows require an interactive Windows session.
• windadd run --dev --verbose is the fastest way to inspect startup problems.