Extensions Overview
Neutralinos framework offers a native API to perform various operating-system-level operations such as accessing filesystem, executing commands, and showing dialog boxes, etc. You may need other native APIs like database connectors to build your applications. But, we can't add all specific APIs to the core and make the framework bloaty. Instead, we offer a WebSocket-based extension system to extend Neutralinojs API without even asking you to build Neutralinojs from source.
You can write custom backend code for your application with any programming language thanks to the flexible extensions API. Also, the extensions API helps you to include Neutralinojs process as a part of any source file.
#
Defining the extensionsFirst, you need to define extensions you use in neutralinojs.config.json
with the following structure.
id
String: A unique key to identify each extension. This id cannot contain any characters except for letters, numbers, and periods.command
String (optional): A cross-platform command to start the extension. Eg:node ${NL_PATH}/extensions/binary/main.js
will work on every platform.commandLinux
String (optional): Extension startup command for Linux.commandDarwin
String (optional): Extension startup command for macOS.commandWindows
String (optional): Extension startup command for Windows.
#
Enable the extensions featureThe extensions API is disabled by default. Enable extensions by adding the following setting to your app config.
#
Connecting an extension with NeutralinojsAs you already noticed, an extension is just a separate process. Neutralinojs starts spawning extension instances during the framework bootstrap process and initiates each extension process with the following process arguments.
--nl-port=<port>
: port of the Neutralinojs server.--nl-token=<token>
: Access token to use the native API.--nl-extension-id=<id>
: Extension identifier.
Now, you can connect with the Neutralinojs server with the above process arguments. Use the following WebSocket URL to initiate a new WebSocket connection.
#
Sending a message from app to an extensionThe extensions API uses an event-based messaging protocol. Every message uses the following JSON structure.
Use the built-in extensions API to send a message to any extension, as shown below.
The above code snippet sends a message to the js.neutralino.sampleextension
extension instance. You can send
messages to extensions with the dispatch
function anytime. If you send a message before the extension connects
with the main process, the Neutralinojs client library queues and sends it when the target extension's connection is
established. In other words, you don't need to worry about extensions' status when you send messages to
extensions.
#
Sending a message from the extension to appWhen you connect your extensions with the Neutralinojs main process, you can call the native API by sending WebSocket messages to the Neutralinojs process directly. Neutralinojs server processes messages based on the following format.
id
String: A UUID v4 string.method
String: Native method name. Eg:window.setTitle
.accessToken
String: Access token generated by the Neutralinojs server.data
Object (optional): Parameters for the native method.
You can invoke the app.broadcast
native method to send messages to all app instances. Register a callback
with the events.on
in the application code to receive the message send by the extension process.
#
Terminating an extension instanceNeutralinojs doesn't send kill signals to all extension instances during exit. Therefore, you have to stop the extension process when the WebSocket-based IPC closes. See the following sample Node.js extension:
https://github.com/neutralinojs/neutralinojs/tree/main/bin/extensions/sampleextension
#
Using Neutralinojs from your source filesThe above approach helps you to extend Neutralinojs API with a custom backend code. Neutralinojs process can spawn multiple extensions as child processes and communicate with the internal messaging protocol. On the other hand, you can spawn Neutralinojs processes from your own processes and communicate with the same messaging protocol. Using this approach, it's possible to write Neutralinojs apps with any backend language.
You can obtain authentication details for the Neutralinojs process by setting your config as below.
The above setting exports authentication details to ${NL_PATH}/.tmp/auth_info.json
with the following format.
Connect with the Neutralinojs process by using the extension API as usual.