{"id":13712540,"url":"https://github.com/hschneider/neutralino-ext-node","last_synced_at":"2025-04-10T04:32:56.409Z","repository":{"id":210593253,"uuid":"726860895","full_name":"hschneider/neutralino-ext-node","owner":"hschneider","description":"A NodeJS Exentsion for NeutralinoJS. Embed Node with all its dependencies into your macOS-, Windows- and Linux-Apps.","archived":false,"fork":false,"pushed_at":"2024-10-10T12:16:24.000Z","size":273,"stargazers_count":16,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-24T16:23:51.154Z","etag":null,"topics":["cross-platform","crossplatform","neutralino","neutralinojs","node","node-js","nodejs"],"latest_commit_sha":null,"homepage":"https://marketmix.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hschneider.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-03T16:07:51.000Z","updated_at":"2025-02-11T11:10:27.000Z","dependencies_parsed_at":"2024-01-14T15:57:39.588Z","dependency_job_id":"af300116-e9b5-47f9-a90f-599c418fb45f","html_url":"https://github.com/hschneider/neutralino-ext-node","commit_stats":null,"previous_names":["hschneider/neutralino-ext-node"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hschneider%2Fneutralino-ext-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hschneider%2Fneutralino-ext-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hschneider%2Fneutralino-ext-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hschneider%2Fneutralino-ext-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hschneider","download_url":"https://codeload.github.com/hschneider/neutralino-ext-node/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248157669,"owners_count":21057050,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cross-platform","crossplatform","neutralino","neutralinojs","node","node-js","nodejs"],"created_at":"2024-08-02T23:01:19.611Z","updated_at":"2025-04-10T04:32:55.876Z","avatar_url":"https://github.com/hschneider.png","language":"JavaScript","funding_links":[],"categories":["Extensions"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://marketmix.com/git-assets/neutralino-ext-node/neutralino-nodejs-header.svg\" width=\"400px\"\u003e\n\u003c/p\u003e\n\n\n# neutralino-ext-node\n\n**A NodeJS Extension for Neutralino \u003e= 5.0.0**\n\nThis extension adds a NodeJS backend to Neutralino with the following features:\n- Embedded NodeJS with all its dependencies for macOS, Linux and Windows Apps.\n- Requires only a few lines of code on both ends.\n- Read all events from the Neutralino app in your NodeJS code.\n- Run NodeJS functions from Neutralino.\n- Run Neutralino functions from NodeJS.\n- All communication between Neutralino and NodeJS runs asynchronously.\n- All events are queued, so none will be missed during processing.\n- Track the data flow between Neutralino and NodeJS in realtime.\n- Use Node's integrated debugger.\n- Works in Window- and headless Cloud-Mode.\n- Terminates the NodeJS Runtime when the Neutralino app quits.\n\n### What this extension is not\n\nThis extension does not make NodeJS transparently available in your NeutralinoJS App. You just call particular functions on a NodeJS Backend and get back the result.\n\n\n\n![Neutralino NodeJS Extension](https://marketmix.com/git-assets/neutralino-ext-node/nodejs-neutralino-extension.gif)\n\n## Run the demo\nThe demo opens a Neutralino app. Clicking on the blue link sends a Ping to NodeJS, which replies with Pong. This illustrates the data-flow in both directions. \n\nBefore running the demo, you need to install the **embedded NodeJS Runtime**. See chapter **\"Integrate into your own Project\"** below. \n\nYou can also use an existing NodeJS installation. In that case, you need to adapt this part of **neutralino.config.json** as follows:\n\n```json\n\"extensions\": [\n    {\n      \"id\": \"extNode\",\n      \"commandDarwin\": \"node --inspect ${NL_PATH}/extensions/node/main.js\",\n      \"commandLinux\": \"node --inspect ${NL_PATH}/extensions/node/main.js\",\n      \"commandWindows\": \"node --inspect ${NL_PATH}/extensions/node/main.js\"\n    }\n  ],\n```\n\nAfter this install the WebSocket module:\n\n```bash\nsudo npm install ws\n```\n\nWhen including the extension in your own project, make sure that **neutralino.config.json** contains this whitelist:\n\n```json\n  \"nativeAllowList\": [\n    \"app.*\",\n    \"os.*\",\n    \"window.*\",\n    \"events.*\",\n    \"extensions.*\",\n    \"debug.log\"\n  ],\n```\n\nAfter this, run these commands in the ext-node folder:\n```commandline\nneu update\nneu run\n```\n\n## ./extensions/node/main.js explained\n\n```JS\nconst NeutralinoExtension = require('./neutralino-extension');\nconst DEBUG = true;     // Print incoming event messages to the console\n\nfunction ping(d) {\n    //\n    // Send some data to the Neutralino app\n\n    ext.sendMessage('pingResult', `NodeJS says PONG, in reply to \"${d}\"`);\n}\n\nfunction processAppEvent(d) {\n    // Handle Neutralino app events.\n    // :param data: data package as JSON dict.\n    // :return: ---\n\n    if(ext.isEvent(d, 'runNode')) {\n        if(d.data.function === 'ping') {\n            ping(d.data.parameter);\n        }\n    }\n}\n\n// Activate Extension\n//\nconst ext = new NeutralinoExtension(DEBUG);\next.run(processAppEvent);\n```\n\nThe extension is activated with the last 2 lines. \n**processAppEvent** is a callback function, which is triggered with each event coming from the Neutralino app.\n\nIn the callback function, you can process the incoming events by their name. In this case we react to the **\"runNode\"** event.\n**data.function** holds the requested NodeJS function and **data.parameter** its data payload as string or JSON.\n\nif the requested function is named ping, we call the ping-function which sends a message back to Neutralino. \n\n**sendMessage()** requires the following parameters:\n\n- An event name, here \"pingResult\"\n- The data package to send, which can be of type string or JSON.\n\nThe **DEBUG** variable tells the NeutralinoExtension to report each event to the console. Incoming events, incoming function calls and outgoing messages are printed in different colors.\nThis makes debugging easier, since you can track the data flow between Neutralino and NodeJS:\n\n![Debug NodeJS](https://marketmix.com/git-assets/neutralino-ext-node/nodejs-console.jpg)\n\n## ./resources/js/main.js explained\n\n```JS\n\nasync function onPingResult(e) {\n...\n}\n\n// Init Neutralino\n//\nNeutralino.init();\n...\nNeutralino.events.on(\"pingResult\", onPingResult);\n...\n// Init NodeJS Extension\nconst NODE = new NodeExtension(true)\n```\n\nThe last line initializes the JavaScript part of the NodeJS extension. It's important to place this after Neutralino.init() and after all event handlers have been installed. Put it in the last line of your code and you are good to go. The const **NODE** is accessible globally.\n\nThe **NodeExtension class** takes only 1 argument which instructs it to run in debug mode (here true). In this mode, all data from the NodeJS extension is printed to the dev-console:\n\n![Debug Meutralino](https://marketmix.com/git-assets/neutralino-ext-node/nodejs-neutralino-console.jpg)\n\nThe **pingResult event handler** listens to messages with the same name, sent by sendMessage() on Node's side. \n\nIn **index.html**, you can see how to send data from Neutralino to NodeJS, which is dead simple:\n```html\n\u003ca href=\"#\" onclick=\"NODE.run('ping', 'Neutralino says PING!');\"\u003eSend PING to Node\u003c/a\u003e\u003cbr\u003e\n```\n\n**NODE.run()** takes 2 arguments:\n\n- The NodeJS function to call, here \"ping\"\n- The data package to submit, either as string or JSON.\n\nBelow this link, you see\n```html\n\u003ca id=\"link-quit\" href=\"#\" onclick=\"NODE.stop();\" style=\"display:none\"\u003eQuit\u003c/a\u003e\n```\n**NODE.stop()** is only required, when running Neutralino in cloud-mode. This will unload the NODE runtime gracefully.\n\n## Integrate into your own project\n\nJust follow these steps:\n\n- Modify **neutralino.config.json**, like mentioned in **\"Run the demo\"**.\n- Copy the **extensions** folder to your project.\n- Adapt the JS code in **extensions/node/main.js** to your needs.\n- Copy **resources/js/node-extension.js** to **resources/js**.\n- Add `\u003cscript src=\"js/node-extension.js\"\u003e\u003c/script\u003e` to your **index.html**\n- Add `const NODE = new NodeExtension(true)` to your **main.js**\n- Add **NODE.run(function_name, data) to main.js** to run NodeJS functions from Neutralino.\n- Add **event listeners to main.js**, to fetch result data from NodeJS.\n\n### Embed NodeJS in your macOS or Linux App\n\nThe following scripts require the **[Git Commandline-Tools](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)** and **Python 3**. \n\nTo embed NodeJS with all its dependencies, enter the following commands in the terminal:\n\n```bash\ncd extensions/node\n./install.sh\n./npm install ws\n```\n\nThis creates a complete NodeJS environment under `extensions/node/_runtime/nodejs`. \n\nIf you need to install further modules, use \n\n```bash\ncd extensions/node\n./npm install MODULE\n```\n\n**install.sh** and **npm** can be deleted before deployment.\n\n### Embed NodeJS in your Windows App\n\nThe following scripts require the **[Git Commandline-Tools](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)** and **Python 3**. \n\nOpen an admin command prompt end enter:\n\n```bash\ncd extensions\\node\ninstall.cmd\nnpm.cmd install ws\n```\n\nThis creates a complete NodeJS environment under `extensions\\node\\_runtime\\nodejs-win`. \n\nIf you need to install further modules, use \n\n```bash\ncd extensions\\node\nnpm.cmd install MODULE\n```\n\n**install.cmd** and **npm.cmd** can be deleted before deployment.\n\n### More about embedded NodeJS\n\nEmbedding is based on NodeEnv by Eugene Kalinin. Thanks to Eugene for this wonderful solution. You can read more about the NodeEnv here: [https://github.com/ekalinin/nodeenv](https://github.com/ekalinin/nodeenv)\n\n## Classes overview\n\n### neutralino-extension.js\n\n| Method                           | Description                                                                                                                     |\n|----------------------------------|---------------------------------------------------------------------------------------------------------------------------------|\n| NeutralinoExtension(debug=false) | Extension class. debug: Print data flow to the terminal.                                                                        |\n| debugLog(msg, tag=\"info\")        | Write a message to the terminal. msg: Message, tag: The message type, \"in\" for incoming, \"out\" for outgoing, \"info\" for others. |\n| isEvent(e, eventName)            | Checks the incoming event data package for a particular event.                                                                  |\n| run(onReceiveMessage)            | Starts the sockethandler main loop. onReceiveMessage: Callback function for incoming messages.                                  |\n| sendMessage(event, data=null)    | Send a message to Neutralino. event: Event-name, data: Data package as string or JSON.                                          |\n\n### node-extension.js\n\n| Method                    | Description                                                                                    |\n|---------------------------|------------------------------------------------------------------------------------------------|\n| NodeExtension(debug=false) | Extension class. debug: Print data flow to the dev-console.                                    |\n| async run(f, p=null)      | Call a NodeJS function. f: Function-name, p: Parameter data package as string or JSON.       |\n| async stop()              | Stop and quit the NodeJS extension and its parent app. Use this if Neutralino runs in Cloud-Mode. This is called automatically, when the browser tab is closed. |\n\n## More about Neutralino\n\n- [NeutralinoJS Home](https://neutralino.js.org) \n\n- [Neutralino Build Automation for macOS, Windows, Linux](https://github.com/hschneider/neutralino-build-scripts)\n\n- [Neutralino related blog posts at marketmix.com](https://marketmix.com/de/tag/neutralinojs/)\n\n\n\n\u003cimg src=\"https://marketmix.com/git-assets/star-me-2.svg\"\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhschneider%2Fneutralino-ext-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhschneider%2Fneutralino-ext-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhschneider%2Fneutralino-ext-node/lists"}