Neutralinojs Documentation

Neutralinojs provides a built-in shared key-value storage system that acts like a global LocalStorage across all Neutralinojs modes.

All data records are persisted in a .storage directory located at the root of your application. To manually wipe all storage data, you can delete this .storage directory.

Neutralinojs applications can run in four distinct modes depending on your deployment requirements. The default mode is window.

• window: Runs the application in a native window using the operating system's theme. Best for cross-platform desktop application development.
• browser: Loads the application in the user's default web browser. This allows web applications to access the operating system layer via Neutralinojs while maintaining security controls.
• cloud: Runs the Neutralinojs process as a background server. This mode allows you to expose your application to a public network or the internet, or use it as a lightweight message broker on bare-metal servers, VMs, or containers.
• chrome: Runs the application as a Chrome/Chromium application, making the web app feel more like a native application.

Neutralinojs restricts arbitrary native API execution for security. To use native functions (like os.*), you must ensure they are included in the nativeAllowList within your configuration file.

Example configuration allowing the os namespace:

"nativeAllowList": [
    "app.*",
    "os.*",
    "debug.log"
]

When Neutralinojs spawns an extension, it sends a JSON object via standard input (stdin) containing connectivity details. The extension must use these details to establish a WebSocket connection to the Neutralinojs server.

Connection Details (from stdin):

• nlPort: The port of the Neutralinojs server.
• nlToken: Access token for the native API.
• nlConnectToken: Token required for WebSocket connection initialization.
• nlExtensionId: The unique identifier for the extension.

WebSocket URL Format: ws://localhost:{nlPort}?extensionId={nlExtensionId}&connectToken={nlConnectToken}

Native API calls follow a WebSocket-based communication pattern between the JavaScript client library and the Neutralinojs server:

1. Invocation: You call a JavaScript method (e.g., Neutralino.os.getEnv).
2. Request: The client library sends a WebSocket message to the Neutralinojs server. The library uses a task pool and a unique UUID string to map server responses back to the original request.
3. Execution: The Neutralinojs server executes the requested native operation on the operating system.
4. Response: The server sends a WebSocket message back to the client with the result.
5. Resolution: The client library resolves the original JavaScript Promise with the received data.

Neutralinojs can be extended beyond JavaScript using two primary IPC (Inter-Process Communication) methods:

1. Extensions IPC: Allows you to extend the framework using any programming language.
2. Child Processes IPC: Allows you to use Neutralinojs as part of any source file by interacting with child processes.

To create a plugin, develop an npm package that exports an index.js file. The CLI uses this file as an interface to register new commands using a register function. The plugin uses a pattern similar to the commander package for defining command strings, options, and actions.

// index.js
module.exports = {
  command: 'commandname <action>',
  register: (command, modules) => {
    command.option('--option1 --option2')
     .action((action, command) => {
        // your logic goes here..
     });
  }
}