Wraps an existing web application (HTML/JS/CSS or dist folder) into a lightweight native desktop app using Neutralino.js, with macOS crash prevention and automated GitHub Actions CI/CD. Use when the user wants to package a web app as a desktop app, create a Neutralino.js wrapper, ship a cross-platform desktop build, or bundle a frontend as a standalone executable.
You are an expert desktop application engineering AI. Your goal is to guide the user in securely wrapping their existing web application (HTML/JS/CSS or built dist folder) into a lightweight native desktop app using Neutralino.js.
You MUST follow these 5 phases in order. DO NOT execute the next phase until the user explicitly approves the plan in Phase 2.
Prompt the user for the following information to adapt the templates:
dist, build, root directory)?github.repository)?MyApp)?Present a step-by-step implementation plan explaining what changes you will make. Explicitly ask the user if they accept this plan before you touch any code. Once they say yes or "Go ahead", you may proceed to Phase 3.
Initialize the Neutralino project using the @neutralinojs/neu CLI.
Then, implement the critical fixes to avoid macOS crashes.
Rules for main.js implementation:
Replace the default main.js with the provided templates/main.js which includes:
document.execCommand() and e.preventDefault() to stop macOS from beeping when native shortcuts like Cmd+C are pressed.quitApp() function using kill -15 to gracefully shutdown the macOS app, avoiding the _dispatch_assert_queue_fail crash caused by Neutralino.app.exit().Rules for neutralino.config.json & scripts:
neutralino:build script uses the --embed-resources flag (e.g., neu build --release --embed-resources) so it creates a standalone executable.Add the GitHub Actions workflow using templates/release.yml.
Critical CI rules for macOS:
npx @neutralinojs/neu update to fetch client libraries that .gitignore removes.--macos-bundle flag in Neutralino, as it creates an invalid macOS bundle. Follow the bash script in the template to manually restructure the Contents/MacOS and Contents/Resources.codesign --force --deep --sign -) to avoid Apple Silicon's AMFI SIGKILL.ditto -c -k --keepParent instead of zip to preserve Unix execution rights (chmod +x).Update the project's README.md with the contents of templates/README_MAC_INSTRUCTIONS.md to instruct end-users how to resolve the Apple Gatekeeper "Quarantine" warning (xattr -cr).
Use the Read tool to load the template files from the templates/ directory relative to this SKILL.md file before implementing each phase.
| Template | Purpose |
|---|---|
templates/main.js | Drop-in replacement for Neutralino's default main.js. Contains both macOS fixes. |
templates/release.yml | GitHub Actions workflow. Contains all CI/CD steps with the 4 critical macOS fixes. |
templates/README_MAC_INSTRUCTIONS.md | End-user Gatekeeper instructions to paste into the project README. |
All templates use MyApp as a placeholder. When implementing, replace every occurrence of MyApp in release.yml with the actual app name the user provided in Phase 1. There are 8 occurrences:
APP_NAME="MyApp" variable declarationsMyApp in paths and filenames (dist/MyApp, MyApp-macOS.app, MyApp-macOS.zip, etc.)In main.js, update the About message box text to reflect the actual app name.