Documentation
Everything about Owear, read straight from the repository — always up to date.
Getting started
Dev and build
This page explains what ow dev and ow build actually do, so you can reason
Installation
Owear ships as a CLI (@owear/cli) plus a per-platform runtime package that
Project structure
A scaffolded app (ow create my-app) looks like this
Quick start
This page gets a window on your screen with as little ceremony as possible.
Your first app
We will build Notes, a small app that
Guides
Auto-update
Owear's updater downloads only what changed (block delta), verifies integrity
Clipboard and shell
Two small modules for OS integration clipboard (text and images) and shell
Debugging
Open the inspector for a window from the renderer
Dialogs and notifications
Two modules cover user-facing prompts dialog (native file pickers and message
Embedded webviews
The webview builtin lets you create and control child webviews inside a
Filesystem (fs) and paths (path)
fs is a stock .owm module covering reads, writes, metadata, fd-style
Global shortcuts
The globalshortcut module registers keyboard shortcuts that work even when your
Installers
An Owear installer is another Owear app that carries your app as an embedded
IPC (renderer ↔ main process)
Owear is designed so the renderer talks to the kernel directly. The main process
Main process
The main process is an optional Node program (the "sidecar") that the kernel
Menus and tray
Menus are built in the main process with @owear/core and dispatched back to
Migrating from Electron
Owear deliberately mirrors Electron's main-process API, so most of the port is
Native addons (N-API)
Owear does not embed its own Node engine. The main process runs on a real
Native modules (.owm)
A native module is a compiled shared library that the kernel loads at runtime
Networking
The net module performs HTTP(S) requests from native code, bypassing the
Packaging
ow build app turns your project into a distributable artifact. It first runs
Processes and PTY
The process module spawns child processes with piped stdio and provides a real
Renderer API (window.ow)
The kernel injects window.ow into every document it loads. This object is your
Safe storage
safeStorage encrypts small secrets (tokens, passwords, keys) using the
Screen and power
Two modules cover environment awareness screen (monitors and cursor) and
Security
Owear gives your UI a direct, powerful bridge to native code. That is the point —
Sessions and downloads
The session builtin manages the WebView's cookies, cache, proxy, and downloads.
Theme
The theme module reads the OS light/dark preference, can force a preference,
Windows (BrowserWindow)
BrowserWindow is the main-process handle for a native window. Its API mirrors
API
Native modules
Every API in Owear lives in api/<name/ and is declared by a manifest
Renderer API — window.ow
The kernel injects window.ow into every document it loads. All calls from the
@owear/core SDK
@owear/core is the main-process SDK. It talks to the kernel over a control
app (native)
Application lifecycle helpers coupled to the kernel.
app
The application object in the main process. Import it from @owear/core.
capturer
Screen capture and available sources.
autoUpdater
Client-side auto-update in the main process. Extends EventEmitter.
clipboard
System clipboard text and images (PNG), via the OS clipboard.
defineBridge
Defines the app ↔ installer ↔ uninstaller contract in owear.bridge.ts. The
crashreporter
Captures native crashes with a signal + backtrace log.
BrowserWindow
A BrowserWindow is the main-process handle for a native window. It extends
dialog
Native file pickers and message boxes.
dialog
Native file pickers and message boxes, backed by the dialog module.
fs
Filesystem module. Cross-platform C++ standard filesystem with per-platform
installer
The SDK around the native installer module. Only available in binaries built in
globalshortcut
System-wide keyboard shortcuts.
Menu and MenuItem
Menus are built in the main process. Clicks run main-process handlers (and are
installer
Installer/uninstaller operations on the embedded payload.
nativeImage and NativeImage
A small image class with no native dependencies a full PNG codec (using
menu
Context menus from a declarative JSON template. Menu clicks are emitted as
Native module access
Call any loaded native module from the main process, and introspect what is
net
Native HTTP(S) requests without CORS, plus file downloads with SHA-256.
Node IPC (app.handle / app.send)
The bridge between the renderer and the main process for features that need Node.
node
Bridge from the renderer to the main (Node) process.
Message ports
A bidirectional channel between the main process and a renderer, modeled after
notification
System notifications.
powerMonitor and powerSaveBlocker
Energy awareness in the main process.
path
Pure path math plus OS standard directories.
protocol
Register custom schemes served either from a directory or from a main-process
power
Battery, idle, session lifecycle (suspend/shutdown/lock), and sleep inhibitors.
safeStorage
Encrypt small secrets using the OS. Backed by the native safestorage module.
process
Spawn child processes with piped stdio and open real PTYs for interactive
screen
Multi-monitor information and cursor position. screen is an EventEmitter that
safestorage
OS-backed encryption for small secrets.
session
Permissions and session partitions. Cookie/cache/proxy/download operations live
screen
Monitors, primary display, cursor position, and change events.
theme / nativeTheme
Read and control the OS light/dark preference. nativeTheme is an alias of
session
WebView session management cookies, cache, proxy, downloads, user agent, spell
Tray
A Tray is a system tray icon, reusing the Menu type for its context menu.
shell
Integration with the system's browser and file manager.
WebContents
win.webContents exposes the window's web content, mirroring Electron's naming.
theme
System light/dark preference, forcing, and change events.
webRequest
Intercept requests made by the WebView. Handlers can cancel or redirect.
tray
System tray icon with a context menu.
Workers
app.forkWorker launches a Node child process with an IPC channel — the
updater
Native primitives for auto-update state inspection and atomic apply + relaunch.
webview
Embedded child webviews inside a window.
window
Window extras coupled to the WebView, plus the internal ow-window builtin for
Architecture
Bridge
The bridge is the kernel-injected script that gives every document window.ow,
Kernel and lifecycle
The kernel is the native owear binary. This page describes its bootstrap and
Native module ABI
The module ABI is the stable C interface between the kernel and .owm shared
Architecture overview
Owear is built from three cooperating pieces, plus an on-demand module system.
Testing
Owear has two test layers fast C++ unit tests and E2E suites that drive a real
Reference
CLI reference
The ow command-line tool scaffolds, develops, builds, and packages Owear apps.
Linux
Linux is the reference platform the kernel, stock modules, and E2E suites are
Control protocol
The kernel exposes a control socket that the Node SDK (and any custom
C++ API (include/ow/)
The public C++ headers declare the contracts shared by all supported platforms.
Windows
With the precompiled runtime (@owear/win32-x64) you do not need
Environment variables
The kernel, the CLI, and the SDK read these OW variables. ow dev and
Module manifests
Every API lives in api/<name/ and is declared by a manifest,
Contributing
Adding an API
An API is a folder api/<name/ with a manifest, a CMake recipe, and sources.
Architecture rules
Four rules explain most decisions in the repo. Breaking them either breaks the
Manual testing in the starter
examples/starter is the reference app used to exercise every subsystem by hand.
Contributing setup
Same as the linux CI job
Changelog
Changelog
One file per release — changelog-<version>.md (for example changelog-0.1.1.md).
0.1.1
First release distributed through npm, with the modular API registry and the Linux runtime as a package.
0.1.2
Cross-platform distribution release with the Windows runtime as a package.
0.1.3
Windows window fix (blank / "not responding"), the Linux → Windows cross-compilation toolchain, titleBarOverlay, a Node bridge, and the C1–C10 app shell.
0.1.4
Installer system (D1) improvements and its default template, plus the draw.io port as an example with its own installer.