electron-mac-dock-icon-switcher

Change your app's Dock icon on macOS, so it persists after your app quits.

You should install this in devDependencies because you'll configure your build process to copy the built .docktileplugin bundle into a folder inside your app bundle. Because of this, the switching icons can only work with your production app, not when running with the electron binary used in development.

Not allowed in Mac App Store

Last I heard, Apple does not allow apps with a docktileplugin in the Mac App Store.

Install

Xcode Requirements

You must have xcodebuild installed and working properly. It comes with Xcode, but if there's an error, you may need to run sudo xcode-select --reset or use the -switch argument to set the location of your Xcode tools.

1. Install in devDependencies

npm install --save-dev electron-mac-dock-icon-switcher

2. Set Variables in .npmrc

You must add the three variables in your app's .npmrc file. Each string must be unique to your app.

• dock_icon_notification_key is used as the system-wide macOS notification key for the "set" icon action. It is typically a reverse dns style string.
• dock_icon_plugin_bundle_identifier is used as the unique identifier of the plugin bundle. It is typically a reverse dns style string. Note that this should be different from your app's bundle identifier.
• dock_icon_class_name is used as the class name of the plugin that is loaded by the dock. It is typically a camel case first-letter-capitalized string, with a prefix unique to the developer or your project.

An example .npmrc file:

dock_icon_notification_key=com.demo.docktile.set
dock_icon_plugin_bundle_identifier=com.demo.docktile.plugin
dock_icon_class_name=MyDemoDockTilePlugin

Changing these variables after installing

If you change any of these values after running once, first rebuild dependencies with npm rebuild, then you'll also need to clear the dock's cache: Quit the app, remove it app from the dock, wait 5 seconds, then restart the Dock and SystemUIServer services:

sudo killall Dock
sudo killall SystemUIServer

3. Build Phase Requirements

1. Set NSDockTilePlugIn in your app's Info.plist
2. Copy DockTile.docktileplugin bundle to your app's bundle in a folder called PlugIns

Here's an example using electron-forge in your forge.config.cjs file:

module.exports = {
	extendInfo: {
		NSDockTilePlugIn: "DockTile.docktileplugin",
	},
	packagerConfig: {
		afterComplete: [
			(buildPath, electronVersion, platform, arch, callback) => {
				if (platform == "darwin") {
					// Copy the plugin to the app bundle
					const fs = require("fs");
					const path = require("path");
					const pluginPath = path.join(
						__dirname,
						"node_modules",
						"electron-mac-dock-icon-switcher",
						"build",
						"Release",
						"DockTile.docktileplugin"
					);
					const pluginDest = path.join(
						buildPath,
						"MyApp.app", // TODO: replace with your bundle name
						"Contents",
						"PlugIns",
						"DockTile.docktileplugin"
					);
					fs.mkdirSync(pluginDest, { recursive: true });
					fs.cpSync(pluginPath, pluginDest, { recursive: true, overwrite: true });
				}
				callback();
			},
		],
	}
	...
}

Signing

You may need to sign the DockTile.docktileplugin bundle before distributing your app.

TODO: add instructions for signing with electron-forge

Debugging

Build manually after checking out this repository:

./build.sh

Fixes some xcodebuild cli errors:

sudo xcode-select --reset

Check the plugin's binary to make sure your notification key is set correctly:

strings ./build/Release/DockTile.docktileplugin/Contents/MacOS/DockTile