| name | macos2linuxapp |
| description | Convert a macOS Electron app (from .dmg) into a runnable Linux Electron app. Use when the user needs to port a macOS-only Electron desktop application to Linux, build a .deb/.rpm package from a macOS DMG, patch app.asar for Linux window behavior, or fix startup crashes after such conversion (e.g., missing chunks, t.join errors, transparent background flickering, deb dependency issues). |
macOS Electron App → Linux Converter
This skill guides the conversion of a macOS Electron app (distributed as .dmg) into a native Linux app, including packaging as .deb.
When this skill triggers
- Porting a macOS-only Electron app to Linux
- Building
app.asar and native modules for Linux from a macOS DMG
- Patching Linux window behavior (icon, menu bar, background color)
- Fixing post-conversion startup crashes (
product-name missing, t.join is not a function, flickering)
- Packaging the result as
.deb, .rpm, or running directly from a folder
High-level workflow
- Check dependencies: Node.js 20+, npm, python3, modern 7zz (24.09+), curl, unzip, make, g++.
- Extract the DMG → locate
.app → extract app.asar with npx asar.
- Rebuild native modules (
better-sqlite3, node-pty, etc.) for the target Linux/Electron version using @electron/rebuild.
- Remove macOS-only modules (
sparkle-darwin, sparkle.node).
- Patch Linux UI: use
scripts/patch-linux-window-ui.js.
- Critical: do not hardcode
t.join; detect the minified path variable name at patch time. See the bundled script for the exact regex.
- Repack
app.asar with npx asar pack.
- Download Linux Electron runtime and assemble the app directory.
- Package (
.deb via dpkg-deb, or other formats).
Bundled resources
- scripts/patch-linux-window-ui.js — fixed Linux window patch script that detects the minified
path variable dynamically.
- references/workflow.md — detailed step-by-step conversion instructions.
- references/troubleshooting.md — fixes for common post-conversion errors (
t.join, missing chunks, deb dependencies, flickering, 7zip failures).
Quick fix reminders
| Symptom | Typical cause | Fix |
|---|
Cannot find module './product-name-XXXX.js' | Broken/incomplete asar | Re-extract from original DMG and repack |
t.join is not a function | Hardcoded t.join in patch script against new bundle | Use dynamic path var detection (see bundled script) |
dpkg: depends on nodejs/npm/p7zip-full | Build tools listed in control Depends: | Remove build-essential, nodejs, npm, p7zip-full, python3, unzip from Depends: |
| Transparent window flickering on Linux | backgroundColor: #00000000 | Patch to opaque dark/light colors for Linux |
| 7z cannot open DMG | Old p7zip (16.02) | Use 7zz 24.09+ |
