trayjs

Cross-platform system tray for Node.js. Works on Linux, macOS and Windows.

Packages

Package	Description
@trayjs/trayjs	Node.js API
@trayjs/linux-x64	Native binary for Linux x64
@trayjs/linux-arm64	Native binary for Linux arm64
@trayjs/darwin-x64	Native binary for macOS x64
@trayjs/darwin-arm64	Native binary for macOS arm64
@trayjs/win32-x64	Native binary for Windows x64
@trayjs/win32-arm64	Native binary for Windows arm64

Quick start

npm install @trayjs/trayjs

import { Tray } from '@trayjs/trayjs';

const tray = new Tray({
  tooltip: 'My App',
  icon: { png: 'icon.png', ico: 'icon.ico' },
  onMenuRequested: () => [
    { id: 'open', title: 'Open' },
    { id: 'recent', title: 'Recent', items: [
      { id: 'file1', title: '~/notes.md' },
      { id: 'file2', title: '~/todo.txt' },
    ]},
    { separator: true },
    { id: 'quit', title: 'Quit' },
  ],
  onClicked: (id) => {
    if (id === 'quit') tray.quit();
  },
});

tray.on('close', () => process.exit(0));

API

new Tray(options)

Option	Type	Description
icon	Icon	Icon file paths (see Icon below)
tooltip	string	Tray tooltip text
onMenuRequested	() => MenuItem[] | Promise<MenuItem[]>	Called every time the tray menu is opened
onClicked	(id: string) => void	Called when a menu item is clicked

Icon

Field	Type	Description
png	string	Path to PNG icon file (used on macOS and Linux)
ico	string	Path to ICO icon file (used on Windows)

MenuItem

Field	Type	Description
id	string	Unique identifier
title	string	Display text
tooltip	string	Hover tooltip
enabled	boolean	Clickable (default true)
checked	boolean	Show check mark
separator	boolean	Render as separator line
items	MenuItem[]	Submenu items

Methods

• tray.setIcon(icon) — update the icon at runtime (takes an Icon object)
• tray.setMenu(items) — set menu items directly
• tray.setTooltip(text) — update the tooltip at runtime
• tray.quit() — close the tray

Events

• 'ready' — tray is visible and accepting commands
• 'close' — tray process exited

Architecture

Each platform has a native tray binary (Objective-C on macOS, Win32 C on Windows, GTK/AppIndicator C on Linux). The Node.js wrapper communicates with it over stdin/stdout using JSON-lines.

The correct platform-specific binary is installed automatically via npm optional dependencies.

Development

git clone <repo>
cd trayjs
npm install

Native binaries are built by CI. Each GitHub Actions run produces downloadable artifacts for all platforms, ready to publish to npm.