https://github.com/davidcann/electron-mac-dock-icon-switcher

Change your app's Dock icon on macOS, so it persists after your app quits.
https://github.com/davidcann/electron-mac-dock-icon-switcher

electron macos

Last synced: about 10 hours ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/davidcann/electron-mac-dock-icon-switcher
• Owner: davidcann
• Created: 2023-11-12T03:12:19.000Z (11 months ago)
• Default Branch: main
• Last Pushed: 2023-11-12T03:32:54.000Z (11 months ago)
• Last Synced: 2024-03-26T07:44:05.159Z (6 months ago)
• Topics: electron, macos
• Language: Objective-C
• Homepage:
• Size: 114 KB
• Stars: 1
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# 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