Docs

macOS App Name in Dev — Build Notes

Build reference for the app-name mismatch on macOS: dev showed Electron, prod shows Tranquil. Says why they differ, why the obvious app.setName() fix does not work, the fix that does, and what governs the name in each build so nobody re-litigates it when touching packaging.

⚠️ Correction (2026-07-29). The “The fix” section below is wrong: patching CFBundleName in the dev bundle’s Info.plist does not change the visible menu-bar/dock name — it stays “Electron”. This was disproven exhaustively (unique bundle id, valid re-sign, re-registration, executable rename all failed; the machine has multiple node_modules Electron.app installs colliding on com.github.Electron). The plist patch only corrects Finder/LaunchServices metadata. The correct name comes from the packaged build. See App Icon & Dev App-Name — Session Notes and ADR-0020 for the current, accurate account.

Status

Superseded (name) / see ADR-0020. The Info.plist patch scripts/dev.js applies is retained (it fixes Finder/LaunchServices metadata) but does not fix the visible dev app name.

The symptom

In dev (yarn start), the macOS menu bar’s bold application menu and the dock label read “Electron” — e.g. “About Electron”, “Quit Electron” — instead of “Tranquil”.

Root cause

yarn start runs Electron’s own unbranded app bundle (node_modules/electron/dist/Electron.app). On macOS, the OS reads the bold application-menu title and the dock label from the running bundle’s Info.plist at process launch — specifically CFBundleName / CFBundleDisplayName, both of which are "Electron" in the stock bundle:

CFBundleName        => "Electron"
CFBundleDisplayName => "Electron"
CFBundleExecutable  => "Electron"

It does not read package.json, and the app-menu template label: 'Pulsar' in src/main-process/application-menu.js is overridden by AppKit and does not drive the bold title.

Why `app.setName('Tranquil')` does NOT fix it

The tempting fix is app.setName('Tranquil') early in the main process. It does not work for the menu bar / dock on macOS. app.setName() changes the runtime value returned by app.getName(), but macOS has already taken the application-menu and dock name from the bundle’s Info.plist at launch, and setName() does not push a new value back to the OS for the running process. Confirmed empirically (quit + relaunch still showed “Electron”). So the name must be corrected in the plist before the process starts. See the Electron application-menu docs — on macOS the first submenu always carries the application’s name, which comes from the bundle.

The fix

scripts/dev.js patches the dev bundle’s Info.plist right before spawning Electron (patchMacAppName):

macOS-only (process.platform === 'darwin').
Sets CFBundleName and CFBundleDisplayName to "Tranquil" via /usr/libexec/PlistBuddy.
Idempotent (skips the write when already correct) and best-effort (any failure is swallowed so the app still launches with the default name).
Runs on every yarn start, so it self-heals after a yarn install reinstalls Electron and resets the stock plist.

Because the OS reads the plist at launch, the new name appears on the very next yarn start.

Dev vs. packaged — what governs the name

Build	Name source	Correct without the patch?
Dev (`yarn start`)	running Electron bundle `Info.plist` `CFBundleName` = “Electron”	❌ — `dev.js` patches it
Packaged (electron-builder)	packaged bundle `CFBundleName` from `productName` = “Tranquil” (`package.json`)	✅ already correct

The dev patch only touches node_modules/electron/dist/..., which never ships. Packaged builds get their bundle name from electron-builder’s productName, so they are unaffected and already say “Tranquil”.

Notes

Config/data paths are unaffected — ~/.tranquil is set explicitly via atom-paths, not derived from the app name.
app.getName() already returned “Tranquil” in dev via productName; only the OS-level menu/dock name needed the plist patch.