Neutralino.js Platform Skill

Consolidated skill for building cross-platform desktop applications with Neutralino.js. Use decision trees below to find the right APIs and configuration options, then load detailed references.

When to Apply

Building desktop utilities with file system operations
Executing system commands or managing processes
Creating apps with tray icons, notifications, or clipboard integration
Accessing system information (CPU, memory, displays)

Critical Rules

Follow these rules in all Neutralino.js code:

Always use
neu create <path>
for new projects unless explicitly asked to create from scratch.
Import
@neutralinojs/lib
for frontend frameworks (React, Vue, etc.) instead of including
```
neutralino.js
```
directly.
Never use
tokenSecurity: none
when exposing native APIs - always use
```
one-time
```
(default) for security.
Configure
nativeAllowList
and
nativeBlockList
to restrict API access and enhance security.
Call
Neutralino.init()
before using any native API methods.
Handle window close events properly using
```
events.on('windowClose')
```
- never rely solely on the close button.
Initialize First: Call
```
Neutralino.init()
```
before any native API usage, see below:

javascript

// WRONG - calling APIs before initialization
await Neutralino.os.getEnv('USER');

// RIGHT - initialize then use APIs
Neutralino.init();
await Neutralino.os.getEnv('USER');

Handle Window Close: Always implement windowClose handler to prevent hanging processes

javascript

// WRONG - missing exit handler
Neutralino.init();

// RIGHT - proper cleanup on window close
Neutralino.init();
Neutralino.events.on("windowClose", () => {
  Neutralino.app.exit();
});

Error Code Patterns: Native API errors use specific codes (

NE_FS_*

NE_OS_*

NE_RT_*

)

javascript

// Check for specific filesystem errors
try {
  await Neutralino.filesystem.readFile('./config.txt');
} catch(err) {
  if (err.code === 'NE_FS_NOPATHE') {
    // File doesn't exist
  } else if (err.code === 'NE_FS_FILRDER') {
    // File read error
  }
}

How to Use This Skill

Reference File Structure

Neutralino.js references follow a hierarchical structure. Cross-cutting concepts and how-to guides are separate.

API References in

./references/api/

```
overview.md
```
- All API namespaces and architecture
```
app.md
```
- Application lifecycle, config, broadcasting
```
window.md
```
- Window management (create, focus, size, tray)
```
filesystem.md
```
- File operations, watchers, paths
```
os.md
```
- OS operations, environment variables, spawning processes
```
storage.md
```
- Key-value storage (SQLite-based)
```
clipboard.md
```
- System clipboard access
```
computer.md
```
- System info (memory, OS version)
```
events.md
```
- Event system (on, off, dispatch, broadcast)
```
extensions.md
```
- Extension communication
```
custom.md
```
- Custom method execution
```
resources.md
```
- Bundle resource access
```
server.md
```
- Server info and configuration
```
updater.md
```
- Auto-updater functionality
```
init.md
```
- Initialization API
```
error-codes.md
```
- Error code reference
```
global-variables.md
```
- Predefined global variables

CLI Reference in

./references/cli/

```
neu-cli.md
```
- All CLI commands (create, run, build, update, etc.)
```
internal-cli-arguments.md
```
- Framework binary CLI arguments

Configuration in

./references/configuration/

```
neutralino.config.json.md
```
- Complete config reference
```
modes.md
```
- Application modes (window, browser, cloud, chrome)
```
project-structure.md
```
- Project directory layout

Getting Started in

./references/getting-started/

```
introduction.md
```
- What is Neutralino.js, features, comparisons
```
using-frontend-libraries.md
```
- React, Vue, Angular integration

How-To Guides in

./references/how-to/

```
extensions-overview.md
```
- Building and using extensions
```
auto-updater.md
```
- Implementing auto-updates

Distribution in

./references/distribution/

```
overview.md
```
- Building and distributing applications

Reading Order

Start with
```
getting-started/introduction.md
```
for overview

Then read based on your task:

Creating new app ->
```
cli/neu-cli.md
```
(neu create)
Using native APIs ->
```
api/overview.md
```
+ specific namespace
Window management ->
```
api/window.md
```
+
```
configuration/modes.md
```
File operations ->
```
api/filesystem.md
```
Configuration ->
```
configuration/neutralino.config.json.md
```
Building extensions ->
```
how-to/extensions-overview.md
```
Auto-updater ->
```
how-to/auto-updater.md
```

Frontend integration ->

getting-started/using-frontend-libraries.md

Distribution ->
```
distribution/overview.md
```

Example Paths

./references/getting-started/introduction.md       # Start here
./references/cli/neu-cli.md                         # CLI commands
./references/api/overview.md                        # All APIs overview
./references/api/filesystem.md                       # File operations
./references/configuration/neutralino.config.json.md # Config reference
./references/how-to/extensions-overview.md          # Extensions
./references/api/window.md                          # Window management

Quick Decision Trees

"I want to create a new Neutralino.js app"

Create app?
├─ Quick start with default template -> neu create myapp
├─ Use custom template -> neu create myapp --template=<account>/<repo>
├─ Integrate with frontend framework -> getting-started/using-frontend-libraries.md
└─ From scratch (expert) -> configuration/neutralino.config.json.md

"I need to manage windows"

Window management?
├─ Create/show window -> api/window.md (window.create, window.show)
├─ Set window size/position -> api/window.md (window.setSize, window.setPosition)
├─ Window focus/maximize/minimize -> api/window.md (window.focus, window.maximize, window.minimize)
├─ System tray icon -> api/window.md (window.setTrayOptions)
├─ Transparent window -> configuration/neutralino.config.json.md (modes.window.transparent)
├─ Borderless window -> configuration/neutralino.config.json.md (modes.window.borderless)
└─ Fullscreen mode -> api/window.md (window.enterFullScreen)

"I need to work with files"

File operations?
├─ Read text file -> api/filesystem.md (readFile)
├─ Write text file -> api/filesystem.md (writeFile)
├─ Read directory -> api/filesystem.md (readDirectory)
├─ Create/remove directory -> api/filesystem.md (createDirectory, remove)
├─ Copy/move files -> api/filesystem.md (copy, move)
├─ Watch file changes -> api/filesystem.md (createWatcher)
├─ File stats (exists, size, modified) -> api/filesystem.md (getStats)
├─ Path operations -> api/filesystem.md (getAbsolutePath, getRelativePath)
└─ File permissions -> api/filesystem.md (getPermissions, setPermissions)

"I need OS-level operations"

OS operations?
├─ Execute system command -> api/os.md (execCommand)
├─ Get environment variable -> api/os.md (getEnv)
├─ Set environment variable -> api/os.md (setEnv)
├─ Spawn process with I/O -> api/os.md (spawnProcess)
├─ Get OS info -> api/computer.md (getOsInfo)
├─ Get memory info -> api/computer.md (getMemoryInfo)
├─ Open external URL -> api/os.md (open)
└─ Path constants (NL_PATH, NL_CWD) -> api/global-variables.md

"I need data storage"

Storage?
├─ Simple key-value storage -> api/storage.md (getData, setData, putData)
├─ Persist data across app restarts -> api/storage.md
└─ Custom database -> how-to/extensions-overview.md (build extension)

"I need to handle events"

Events?
├─ Window close event -> api/events.md (windowClose)
├─ Window focus/blur -> api/events.md (windowFocus, windowBlur)
├─ Tray menu click -> api/events.md (trayMenuItemClicked)
├─ App instance events -> api/events.md (appClientConnect, appClientDisconnect)
├─ Extension events -> api/events.md (extensionReady, extClientConnect)
└─ Custom events -> api/events.md (dispatch, broadcast)

"I need to build and distribute"

Build & distribute?
├─ Build for current platform -> cli/neu-cli.md (neu build)
├─ Create portable ZIP -> cli/neu-cli.md (--release)
├─ Single-file executable -> cli/neu-cli.md (--embed-resources)
├─ Auto-updater -> how-to/auto-updater.md
└─ Distribution overview -> distribution/overview.md

"I need to use extensions"

Extensions?
├─ Overview and concepts -> how-to/extensions-overview.md
├─ Define extensions in config -> configuration/neutralino.config.json.md (extensions)
├─ Enable extensions -> configuration/neutralino.config.json.md (enableExtensions)
├─ Dispatch to extension -> api/extensions.md (dispatch)
├─ Extension receives messages -> how-to/extensions-overview.md (WebSocket protocol)
└─ Extension calls native API -> how-to/extensions-overview.md (app.broadcast)

"I need app lifecycle control"

Lifecycle?
├─ Exit app -> api/app.md (exit)
├─ Kill process (force) -> api/app.md (killProcess)
├─ Restart app -> api/app.md (restartProcess)
├─ Get app config -> api/app.md (getConfig)
├─ Broadcast to all instances -> api/app.md (broadcast)
├─ Read/write stdin/stdout -> api/app.md (readProcessInput, writeProcessOutput)
└─ Initialize client -> api/init.md (init)

"Which mode should I use?"

Application mode?
├─ Desktop app with native window -> window mode (default)
├─ Web app with native features -> browser mode
├─ Background server/API -> cloud mode
├─ Chrome app style -> chrome mode
└─ Details -> configuration/modes.md

"I need security configuration"

Security?
├─ Restrict API access -> configuration/neutralino.config.json.md (nativeAllowList, nativeBlockList)
├─ Token security -> configuration/neutralino.config.json.md (tokenSecurity)
├─ Export auth info -> configuration/neutralino.config.json.md (exportAuthInfo)
└─ Global variables -> api/global-variables.md

"I need to integrate with frontend frameworks"

Frontend integration?
├─ React/Vue/Angular -> getting-started/using-frontend-libraries.md
├─ Import client lib -> npm: @neutralinojs/lib
├─ CLI frontend support -> configuration/neutralino.config.json.md (cli.frontendLibrary)
└─ HMR/DevTools -> cli/neu-cli.md (neu run with dev server)

Product Index

API Namespaces

Namespace	Entry File	Description
app	`./references/api/app.md`	Application lifecycle, config, broadcasting
window	`./references/api/window.md`	Window creation, management, tray
filesystem	`./references/api/filesystem.md`	File operations, watchers, paths
os	`./references/api/os.md`	OS operations, environment, processes
storage	`./references/api/storage.md`	Key-value storage
clipboard	`./references/api/clipboard.md`	Clipboard access
computer	`./references/api/computer.md`	System info (memory, OS)
events	`./references/api/events.md`	Event system
extensions	`./references/api/extensions.md`	Extension communication
custom	`./references/api/custom.md`	Custom method execution
resources	`./references/api/resources.md`	Bundle resources
server	`./references/api/server.md`	Server info
updater	`./references/api/updater.md`	Auto-updater
init	`./references/api/init.md`	Initialization
error-codes	`./references/api/error-codes.md`	Error codes
global-variables	`./references/api/global-variables.md`	Predefined globals

Configuration

Concept	Entry File	Description
Config Reference	`./references/configuration/neutralino.config.json.md`	Complete configuration options
Modes	`./references/configuration/modes.md`	Application modes (window, browser, cloud, chrome)
Project Structure	`./references/configuration/project-structure.md`	Directory layout

CLI

Concept	Entry File	Description
neu CLI	`./references/cli/neu-cli.md`	All CLI commands
Internal Arguments	`./references/cli/internal-cli-arguments.md`	Framework binary arguments

Getting Started

Concept	Entry File	Description
Introduction	`./references/getting-started/introduction.md`	Overview, features, comparisons
Frontend Libraries	`./references/getting-started/using-frontend-libraries.md`	React, Vue, Angular integration

How-To

Concept	Entry File	Description
Extensions	`./references/how-to/extensions-overview.md`	Building and using extensions
Auto Updater	`./references/how-to/auto-updater.md`	Implementing updates

Distribution

Concept	Entry File	Description
Distribution	`./references/distribution/overview.md`	Building and distributing apps

Key Patterns

File Operations

javascript

// Read/write text files
let content = await Neutralino.filesystem.readFile('./data.txt');
await Neutralino.filesystem.writeFile('./output.txt', 'Hello World');

// Binary file operations
let buffer = await Neutralino.filesystem.readBinaryFile('./image.png');
let rawBin = new ArrayBuffer(1);
let view = new Uint8Array(rawBin);
view[0] = 64;
await Neutralino.filesystem.writeBinaryFile('./data.bin', rawBin);

// File stats and existence check
try {
  let stats = await Neutralino.filesystem.getStats('./file.txt');
  console.log(`Size: ${stats.size}, IsFile: ${stats.isFile}`);
} catch(err) {
  if (err.code === 'NE_FS_NOPATHE') {
    console.log('File does not exist');
  }
}

Process Management

javascript

// Execute command and get output
let result = await Neutralino.os.execCommand('python --version');
console.log(result.stdOut);

// Spawn background process with event monitoring
let proc = await Neutralino.os.spawnProcess('ping google.com');

Neutralino.events.on('spawnedProcess', (evt) => {
  if (proc.id === evt.detail.id) {
    switch(evt.detail.action) {
      case 'stdOut':
        console.log(evt.detail.data);
        break;
      case 'stdErr':
        console.error(evt.detail.data);
        break;
      case 'exit':
        console.log(`Exit code: ${evt.detail.data}`);
        break;
    }
  }
});

// Send input to spawned process
await Neutralino.os.updateSpawnedProcess(proc.id, 'stdIn', 'input data');
await Neutralino.os.updateSpawnedProcess(proc.id, 'stdInEnd');

System Tray Integration

javascript

// Set up tray with menu
let tray = {
  icon: '/resources/icons/tray.png',
  menuItems: [
    {id: "show", text: "Show Window"},
    {text: "-"}, // Separator
    {id: "quit", text: "Quit"}
  ]
};

await Neutralino.os.setTray(tray);

// Handle tray menu clicks
Neutralino.events.on('trayMenuItemClicked', (evt) => {
  switch(evt.detail.id) {
    case 'show':
      // Show window logic
      break;
    case 'quit':
      Neutralino.app.exit();
      break;
  }
});

Clipboard Operations

javascript

// Text clipboard
await Neutralino.clipboard.writeText('Hello World');
let text = await Neutralino.clipboard.readText();

// HTML clipboard
await Neutralino.clipboard.writeHTML('<p style="color:red;">Formatted</p>');
let html = await Neutralino.clipboard.readHTML();

// Check clipboard format
let format = await Neutralino.clipboard.getFormat();

System Information

javascript

// CPU information
let cpu = await Neutralino.computer.getCPUInfo();
console.log(`CPU: ${cpu.model}, Cores: ${cpu.physicalCores}`);

// Display information
let displays = await Neutralino.computer.getDisplays();
displays.forEach(display => {
  console.log(`Display ${display.id}: ${display.resolution.width}x${display.resolution.height}`);
});

// Architecture and OS
let arch = await Neutralino.computer.getArch();
let username = await Neutralino.os.getEnv(NL_OS === 'Windows' ? 'USERNAME' : 'USER');

Notifications

javascript

// Basic notification
await Neutralino.os.showNotification('Title', 'Message content');

// Notification with icon type
await Neutralino.os.showNotification('Error', 'Something went wrong', 'ERROR');
// Icon types: INFO, WARNING, ERROR, QUESTION

Common Mistakes

Missing
await
on async calls — All native APIs return promises
Not checking file existence — Use
```
getStats()
```
to verify files exist before operations
Forgetting process cleanup — Always handle spawned process exit events
Invalid tray icon paths — Use
```
/resources/
```
prefix for bundled assets
Missing error handling — Wrap native API calls in try-catch blocks

Resources

Repository: https://github.com/neutralinojs/neutralinojs Documentation: https://neutralino.js.org Client Library (NPM): https://www.npmjs.com/package/@neutralinojs/lib CLI (NPM): https://www.npmjs.com/package/@neutralinojs/neu Discussions: https://github.com/neutralinojs/neutralinojs/discussions

neutralinojs

NPX Install

Tags

SKILL.md Content

Neutralino.js Platform Skill

When to Apply

Critical Rules

How to Use This Skill

Reference File Structure

Reading Order

Example Paths

Quick Decision Trees

"I want to create a new Neutralino.js app"

"I need to manage windows"

"I need to work with files"

"I need OS-level operations"

"I need data storage"

"I need to handle events"

"I need to build and distribute"

"I need to use extensions"

"I need app lifecycle control"

"Which mode should I use?"

"I need security configuration"

"I need to integrate with frontend frameworks"

Product Index

API Namespaces

Configuration

CLI

Getting Started

How-To

Distribution

Key Patterns

File Operations

Process Management

System Tray Integration

Clipboard Operations

System Information

Notifications

Common Mistakes

Resources