{"id":13712526,"url":"https://github.com/hschneider/neutralino-ext-bun","last_synced_at":"2025-04-10T04:33:00.692Z","repository":{"id":208965185,"uuid":"722701037","full_name":"hschneider/neutralino-ext-bun","owner":"hschneider","description":"A Neutralino Bun-Extension. Bun is extremely fast and almost completely NodeJS-compatible JS Runtime. Easy to embed into your Neutralino App.","archived":false,"fork":false,"pushed_at":"2024-09-10T08:12:41.000Z","size":116462,"stargazers_count":12,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-09-10T10:27:19.813Z","etag":null,"topics":["bun","cross-platform","crossplatform","javascript","neutralino","neutralinojs","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-11-23T18:26:25.000Z","updated_at":"2024-09-10T08:11:18.000Z","dependencies_parsed_at":"2024-03-02T20:25:46.178Z","dependency_job_id":"26b025f2-5776-4fb9-906a-a36140d11a1f","html_url":"https://github.com/hschneider/neutralino-ext-bun","commit_stats":null,"previous_names":["hschneider/neutralino-ext-bun"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hschneider%2Fneutralino-ext-bun","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hschneider%2Fneutralino-ext-bun/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hschneider%2Fneutralino-ext-bun/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hschneider%2Fneutralino-ext-bun/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hschneider","download_url":"https://codeload.github.com/hschneider/neutralino-ext-bun/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223424982,"owners_count":17142862,"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":["bun","cross-platform","crossplatform","javascript","neutralino","neutralinojs","nodejs"],"created_at":"2024-08-02T23:01:19.436Z","updated_at":"2024-11-06T22:19:18.718Z","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-bun/neutralino-bun-header.svg\"\u003e\n\u003c/p\u003e\n\n# neutralino-ext-bun\n**A Bun / NodeJS Extension for Neutralino**\n\n\u003e **GREAT NEWS:**\u003cbr\u003eThis extension also works under Windows now.\u003cbr\u003e\n\u003e But keep in mind, that Bun for the native Windows platform is still work in progress.\u003cbr\u003e\n\u003e To install the latest release see **[Windows: Get the latest Bun Beta](https://github.com/hschneider/neutralino-ext-bun?tab=readme-ov-file#windows-get-the-latest-bun-beta)**\u003cbr\u003e\n\u003e If you require a more stable NodeJS solution under Windows, **check out [neutralino-ext-node](https://github.com/hschneider/neutralino-ext-node)**.\n\n### Why Bun?\n\nBun is an all-in-one JavaScript Runtime designed for speed:\n- It is extremely fast, in many cases 4 times faster than NodeJS.\n- Most NodeJS packages are compatible with Bun.\n- You can code in JS, TypeScript, NodeJS, JSX\n- It's powerful API comes with the fastest SQlite driver for JS.\n- It's all contained in a single file, which can be embedded without dependencies.\n\n### Bun: The perfect NodeJS-compatible extension for Neutralino\n\nThis extension adds a Bun backend to Neutralino with the following features:\n- Requires only a few lines of code on both ends.\n- Read all events from the Neutralino app in your Bun code.\n- Run Bun functions from Neutralino.\n- Run Neutralino functions from Bun.\n- All communication between Neutralino and Bun runs asynchronously.\n- All events are queued, so none will be missed during processing.\n- Track the data flow between Neutralino and Bun in realtime.\n- Use Bun's integrated, browser-based debugger.\n- Works in Window- and headless Cloud-Mode.\n- Terminates the Bun Runtime when the Neutralino app quits.\n\n### What this extension is not\n\nThis extension does not make Bun/NodeJS transparently available in your NeutralinoJS App. You just call particular functions on a Bun Backend and get back the result.\n\n\n\n![Neutralino Bun / NodeJS Extension](https://marketmix.com/git-assets/neutralino-ext-bun/bun-nodejs-neutralino.gif)\n\n## Run the demo\nThe demo opens a Neutralino app. Clicking on the blue link sends a Ping to Bun, which replies with Pong.\nThis illustrates the data-flow in both directions. \n\nBefore running the demo, the Bun runtime needs to be installed into the extension folder:\n```bash\ncd ext-bun/extensions/bun\n./install.sh\n```\n\nIf you need to install further Packages, use the **bun.sh script** instead of bun. This starts the relocated runtime\ninstead of your standard Bun installation, e.g.:\n```bash\ncd ext-bun/extensions/bun\n./bun.sh install PACKAGE\n```\n\nWhen including the extension in your own project, make sure that **neutralino.config.json** contains this whitelist:\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-bun folder:\n```commandline\nneu update\nneu run\n```\n\n## Integrate into your own project\nJust follow these steps:\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/bun/main.js** to your needs.\n- Copy **resources/js/bun-extension.js** to **resources/js**.\n- Add `\u003cscript src=\"js/bun-extension.js\"\u003e\u003c/script\u003e` to your **index.html**\n- Add `const BUN = new BunExtension(true)` to your **main.js**\n- Add **BUN.run(function_name, data) to main.js** to run Bun functions from Neutralino.\n- Add **event listeners to main.js**, to fetch result data from Bun.\n\n### All platforms: Create a Bun single-file executable\n\nBun allows to **[build single-file executables](https://bun.sh/docs/bundler/executables)**, containing all scripts and their dependencies. The run-scripts in **extensions/bun** will automatically start binaries called **main-app** (macOS, Linux) or **main-app.exe** (Windows), when main.js is missing.\n\nSo for distributing a binary bundle, all you have to do is:\n\n```bash\ncd extensions/bun\nbun build main.js --compile --outfile main-app\n```\n\nAfter this you can delete theses files and folders from the **extensions/bun** folder:\n\n- *.js\n- *.sh\n- _runtime\n\n### macOS: Embedding Bun into an App-Bundle\n\nThe Bun runtime is extremely optimized for each architecture. As a result, you need different Bun binaries for Intel and \nApple Silicon. So the x64 binary won't run in an arm64 environment, even with Rosetta enabled.\n\nKeep this in mind for your build process, when embedding Bun in your app-bundle. These **[Build Scripts](https://github.com/hschneider/neutralino-build-scripts)** will help you to mange different resources in your build-worflow.\n\n### Windows: Get the latest Bun Beta\n\n#### Prepare your PowerShell environment:\nOpen a PowerShell and enter:\n```bash\nSet-ExecutionPolicy unrestricted\n```\n\n#### Get Bun:\nOpen a fresh PowerShell and enter:\n```bash\ncd ext-bun\nexport BUN_INSTALL=./extensions/bun/_runtime\nirm bun.sh/install.ps1 | iex\n```\n\n#### Upgrade Bun:\nIf your installation is outdated and you want the latest built, enter:\n```bash\ncd ext-bun\nexport BUN_INSTALL=./extensions/bun/_runtime\nbun upgrade\n```\n\n## ./extensions/bun/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', `Bun 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, 'runBun')) {\n        if(d.data.function === 'ping') {\n            ping(d.data.parameter);\n        }\n    }\n}\n\n// Activate Extension\n//\nconst ext = await 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 **\"runBun\"** event.\n**data.function** holds the requested Bun 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- 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 \nfunction calls and outgoing messages are printed in different colors.\nThis makes debugging easier, since you can track the data flow between Neutralino and Bun:\n\n![Debug Bun / NodeJS](https://marketmix.com/git-assets/neutralino-ext-bun/bun-nodejs-console-3.jpg) \n\nEach debug run starts with a link to Bun's integrated, browser-based debugger: \n\n![Debug Bun / NodeJS](https://marketmix.com/git-assets/neutralino-ext-bun/bun-nodejs-neutralino-debug-link.jpg)\n\nCopy \u0026 paste the link into Google Chrome and start your live debug session:\n\n![Debug session in Bun / NodeJS](https://marketmix.com/git-assets/neutralino-ext-bun/bun-nodejs-neutralino-debug.jpg)\n\n## ./resources/js/main.js explained\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 Bun Extension\nconst BUN = new BunExtension(true)\n```\n\nThe last line initializes the JavaScript part of the Bun 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 **BUN** is accessible globally.\n\nThe **BunExtension class** takes only 1 argument which instructs it to run in debug mode (here true). In this mode, all data from the Bun extension is printed to the dev-console:\n\n![Debug Meutralino](https://marketmix.com/git-assets/neutralino-ext-bun/bun-nodejs-neutralino-console.jpg)\n\nThe **pingResult event handler** listens to messages with the same name, sent by sendMessage() on Bun's side. \n\nIn **index.html**, you can see how to send data from Neutralino to Bun, which is dead simple:\n```html\n\u003ca href=\"#\" onclick=\"BUN.run('ping', 'Neutralino says PING!');\"\u003eSend PING to Bun\u003c/a\u003e\u003cbr\u003e\n```\n\n**BUN.run()** takes 2 arguments:\n- The Bun 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=\"BUN.stop();\" style=\"display:none\"\u003eQuit\u003c/a\u003e\n```\n**BUN.stop()** is only required, when running Neutralino in cloud-mode. This will unload the BUN runtime gracefully.\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### bun-extension.js\n\n| Method                    | Description                                                  |\n| ------------------------- | ------------------------------------------------------------ |\n| BunExtension(debug=false) | Extension class. debug: Print data flow to the dev-console.  |\n| async run(f, p=null)      | Call a Bun function. f: Function-name, p: Parameter data package as string or JSON. |\n| async stop()              | Stop and quit the Bun 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 \u0026 Bun\n- [Bun Home](https://bun.sh)\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-bun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhschneider%2Fneutralino-ext-bun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhschneider%2Fneutralino-ext-bun/lists"}