Node Neutralino

Node Neutralino is a NPM Package that lets you write backend code for your Neutralinojs apps, It supports Vanilla JS as well as frontend frameworks.

Table Of Content

Getting Started

You could manually add Node Neutralino to your projects or get started with one of the premade templates!

Templates:

Using Templates:

# Use neutralinojs-community/node-neutralino-vanilla for Vanilla JS template
$ neu create myapp --template neutralinojs-community/node-neutralino-react
$ cd myapp

# Run Neu App
$ neu run

# Build Neu App
$ neu build --clean

Manual Installation:

Add node-neutralino as npm dependency in root of your NEU App.

$ npm i node-neutralino

Add the following config in neutralino.config.json for projectRunner.

// This is required since node-neutralino communicates via neutralinojs extension protocol.
"enableExtensions": true,
"extensions": [
  {
      "id": "js.node-neutralino.projectRunner"
  }
]

// Add projectRunner Config
"cli": {
  "projectRunner": {
    "projectPath": "/", // initCommand, devCommand, buildCommand will run in this folder
    "buildPath": "./node-src/dist/", // Location where built backend file(s) need to be located after buildCommand
    "initCommand": "npm install", // (optional) This command is executed when app is created from a template repo with neu create
    "devCommand": "tsx ./server.ts", // (optional) This command is executed when app is opened in dev mode to run the projectRunner File
    "buildCommand": "tsc" // (optional) This command is executed when app is being built, developers are responsible to make sure that built backend files are located in projectRunner.buildPath after executing this command.
  }
}

Create backend file that imports node-neutralino package and initializes the Neu app.
Example:

// server.ts
import NeutralinoApp from "node-neutralino"

async function main() {
  const app = new NeutralinoApp({
    url: "/",
    windowOptions: {
      enableInspector: false,
    }
  });

  app.init();

  app.events.on("backend.maximize", () => {
    app.window.maximize();
  });
}

main();

Now you can run/build the Neu app with neu-cli easily.

# To run the app
$ neu run

# To build the app
$ neu build --clean

NeutralinoApp Configuration Options

url

The entry URL of the application. Neutralinojs will initially load this URL Ref

windowOptions.title

Title of the native window. Ref

windowOptions.icon

Application icon's file name. Ref

windowOptions.fullScreen

Activates the full-screen mode. Ref

windowOptions.alwaysOnTop

Activates the top-most mode. Ref

windowOptions.enableInspector

Automatically opens the developer tools window. Ref

windowOptions.borderless

Activates the borderless mode. Ref

windowOptions.maximize

Launches the application maximized. Ref

windowOptions.hidden

Make the window invisible. Ref

windowOptions.maximizable

Makes the window maximizable or not. Ref

windowOptions.useSavedState

Save and load the primary window state (width, height, x, y, values and maximized status) automatically. Ref

windowOptions.exitProcessOnClose

If this setting is true, the app process will exit when the user clicks on the close button. Ref

windowOptions.extendUserAgentWith

Extends the default webview-specific user agent string with a custom suffix. Ref

windowOptions.processArgs

(String) Additional command-line arguments for the new window process. Check all supported internal command-line arguments from here

Read more about working with frontend library and config here.

windowOptions.frontendLibrary.patchFile

[String] Location for HTML file for HRM (hot module replacement)

windowOptions.frontendLibrary.devUrl

[String] (Optional) Development Server URL

windowOptions.frontendLibrary.clientLibrary

[String] (Optional) Filename of the Neutralinojs JavaScript library. Ref

windowOptions.frontendLibrary.resourcesPath

[String] (Optional) Path of your application resources. Ref

windowOptions.frontendLibrary.documentRoot

[String] (Optional) Sets the document root for the static server. Ref

windowOptions.frontendLibrary.projectPath

[String] (Optional) Path to resources for frontend lib app. windowOptions.frontendLibrary.devCommand will be executed in this location.

windowOptions.frontendLibrary.devCommand

[String] (Optional) Command to start frontend library development server.

windowOptions.frontendLibrary.waitTimeout

[Number] (Optional) Amount of time to wait in miliseconds to start the development server before the Neu App exits out.

Create your own Project Runner in any language

This is a guide to show you how you can create similar package like node-neutralino in any language, eg: py-neutralino, rust-neutralino, etc.
Steps:
1st Step (Spawning Neutralino Binaries With Process Args):
- Take input from users for all the supported args.
- Spawn Binaries with given args by converting from object to string.
2nd Step (Connect To Neutralino Server):
- To communicate with the spawed app you can connect with the internal server through WebSockets.
- --export-auth-info args can be given to export the auth info used to connect with Neutralino Server.
- --enable-extensions=true can be given in args to enable for extension in server.
- You can follow this guide to connect with the WS server.
- Listens for messages and emit the messages according to its type. Send Message/event when a function is triggered on the connected WS.
3rd Step (Support Frontend Libraries):
- If frontendLib option are provided during spawning the binaries, then few extra steps need to be followed.
- Patch HTML file by including script for global variables.
- Start the given devCommand in projectPath to start the frontend lib dev server.
- Wait for the port to be busy to detect if the development server is started or not.