feat: support Icon Composer files as icon input for macOS (#1806)

* feat: support Icon Composer files as icon input for macOS

* chore: update for feedback

Author: MarshallOfSound

src/icon-composer.ts

@@ -0,0 +1,86 @@
+import { spawn } from '@malept/cross-spawn-promise';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import plist from 'plist';
+import semver from 'semver';
+
+export async function generateAssetCatalogForIcon(inputPath: string) {
+  if (!semver.gte(os.version(), '25.0.0')) {
+    throw new Error(
+      `actool .icon support is currently limited to macOS 26 and higher`
+    );
+  }
+
+  const acToolVersionOutput = await spawn('actool', ['--version']);
+  const versionInfo = plist.parse(acToolVersionOutput) as Record<
+    string,
+    Record<string, string>
+  >;
+  if (
+    !versionInfo ||
+    !versionInfo['com.apple.actool.version'] ||
+    !versionInfo['com.apple.actool.version']['short-bundle-version']
+  ) {
+    throw new Error(
+      'Unable to query actool version. Is Xcode 26 or higher installed? See output of the `actool --version` CLI command for more details.',
+    );
+  }
+
+  const acToolVersion =
+    versionInfo['com.apple.actool.version']['short-bundle-version'];
+  if (!semver.gte(semver.coerce(acToolVersion)!, '26.0.0')) {
+    throw new Error(
+      `Unsupported actool version. Must be on actool 26.0.0 or higher but found ${acToolVersion}. Install XCode 26 or higher to get a supported version of actool.`,
+    );
+  }
+
+  const tmpDir = await fs.mkdtemp(path.resolve(os.tmpdir(), 'icon-compile-'));
+  const iconPath = path.resolve(tmpDir, 'Icon.icon');
+  const outputPath = path.resolve(tmpDir, 'out');
+
+  try {
+    await fs.cp(inputPath, iconPath, {
+      recursive: true,
+    });
+
+    await fs.mkdir(outputPath, {
+      recursive: true,
+    });
+
+    await spawn('actool', [
+      iconPath,
+      '--compile',
+      outputPath,
+      '--output-format',
+      'human-readable-text',
+      '--notices',
+      '--warnings',
+      '--output-partial-info-plist',
+      path.resolve(outputPath, 'assetcatalog_generated_info.plist'),
+      '--app-icon',
+      'Icon',
+      '--include-all-app-icons',
+      '--accent-color',
+      'AccentColor',
+      '--enable-on-demand-resources',
+      'NO',
+      '--development-region',
+      'en',
+      '--target-device',
+      'mac',
+      '--minimum-deployment-target',
+      '26.0',
+      '--platform',
+      'macosx',
+    ]);
+
+    return await fs.readFile(path.resolve(outputPath, 'Assets.car'));
+  } finally {
+    await fs.rm(tmpDir, {
+      recursive: true,
+      force: true,
+    });
+  }
+}

src/mac.ts

@@ -7,6 +7,7 @@ import { notarize, NotarizeOptions } from '@electron/notarize';
 import { signApp } from '@electron/osx-sign';
 import { ComboOptions } from './types';
 import { SignOptions } from '@electron/osx-sign/dist/cjs/types';
+import { generateAssetCatalogForIcon } from './icon-composer';
 
 type NSUsageDescription = {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -25,6 +26,7 @@ type BasePList = {
 interface Plists {
   appPlist?: BasePList & {
     CFBundleIconFile: string;
+    CFBundleIconName: string;
     // eslint-disable-next-line no-use-before-define
     CFBundleURLTypes: MacApp['protocols'];
     ElectronAsarIntegrity: App['asarIntegrity'];
@@ -380,6 +382,10 @@ export class MacApp extends App implements Plists {
       }
     }
 
+    // Copying the icon compose icon mutates the appPlist so must
+    // be run before we update plist files
+    await this.copyIconComposerIcon(this.appPlist);
+
     await Promise.all(
       plists.map(([filename, varName]) =>
         fs.writeFile(
@@ -447,19 +453,42 @@ export class MacApp extends App implements Plists {
     );
   }
 
+  async copyIconComposerIcon(appPlist: NonNullable<Plists['appPlist']>) {
+    if (!this.opts.icon) {
+      return;
+    }
+
+    let iconComposerIcon: string | null = null;
+
+    try {
+      iconComposerIcon = (await this.normalizeIconExtension('.icon')) || null;
+    } catch {
+      // Ignore error if icon doesn't exist, in case only the .icns format was provided
+    }
+    if (iconComposerIcon) {
+      debug(
+        `Generating asset catalog for icon composer "${iconComposerIcon}" file`,
+      );
+      const assetCatalog = await generateAssetCatalogForIcon(iconComposerIcon);
+      appPlist.CFBundleIconName = 'Icon';
+      await fs.writeFile(
+        path.join(this.originalResourcesDir, 'Assets.car'),
+        assetCatalog,
+      );
+    }
+  }
+
   async copyIcon() {
     if (!this.opts.icon) {
       return Promise.resolve();
     }
 
-    let icon;
+    let icon: string | null = null;
 
     try {
-      icon = await this.normalizeIconExtension('.icns');
+      icon = (await this.normalizeIconExtension('.icns')) || null;
     } catch {
       // Ignore error if icon doesn't exist, in case it's only available for other OSes
-      /* istanbul ignore next */
-      return Promise.resolve();
     }
     if (icon) {
       debug(
@@ -540,6 +569,7 @@ export class MacApp extends App implements Plists {
   async create() {
     await this.initialize();
     await this.updatePlistFiles();
+    // Copying icons depends on the plist files being updated
     await this.copyIcon();
     await this.renameElectron();
     await this.renameAppAndHelpers();

src/platform.ts

@@ -195,29 +195,33 @@ export class App {
    *
    * This error path is used by win32 if no icon is specified.
    */
-  async normalizeIconExtension(targetExt: string) {
+  async normalizeIconExtension(targetExt: string): Promise<string | void> {
     if (!this.opts.icon) {
       throw new Error('No filename specified to normalizeIconExtension');
     }
 
-    let iconFilename = this.opts.icon;
-    const ext = path.extname(iconFilename);
-    if (ext !== targetExt) {
-      iconFilename = path.join(
-        path.dirname(iconFilename),
-        path.basename(iconFilename, ext) + targetExt,
-      );
-    }
+    const iconFilenames = Array.isArray(this.opts.icon)
+      ? this.opts.icon
+      : [this.opts.icon];
+    for (let iconFilename of iconFilenames) {
+      const ext = path.extname(iconFilename);
+      if (ext !== targetExt) {
+        iconFilename = path.join(
+          path.dirname(iconFilename),
+          path.basename(iconFilename, ext) + targetExt,
+        );
+      }
 
-    if (await fs.pathExists(iconFilename)) {
-      return iconFilename;
-    } else {
-      /* istanbul ignore next */
-      warning(
-        `Could not find icon "${iconFilename}", not updating app icon`,
-        this.opts.quiet,
-      );
+      if (await fs.pathExists(iconFilename)) {
+        return iconFilename;
+      }
     }
+
+    /* istanbul ignore next */
+    warning(
+      `Could not find icon "${this.opts.icon}" with extension "${targetExt}", skipping this app icon format`,
+      this.opts.quiet,
+    );
   }
 
   prebuiltAsarWarning(option: keyof ComboOptions, triggerWarning: unknown) {

src/types.ts

@@ -434,10 +434,14 @@ export interface Options {
   helperBundleId?: string;
   /**
    * The local path to the icon file, if the target platform supports setting embedding an icon.
+   * 
+   * Only macOS supports multiple paths, every other platform must be a single path. On macOS you can provide
+   * **both** an `.icns` and an `.icon` file. The `.icns` file will be used on macOS < 26 and `.icon` will be used
+   * on macOS >= 26.
    *
    * Currently you must look for conversion tools in order to supply an icon in the format required by the platform:
    *
-   * - macOS: `.icns`
+   * - macOS: `.icon` from Icon Composer (only supported if Xcode 26 or higher is present) or `.icns`
    * - Windows: `.ico` ([See the readme](https://github.com/electron/packager#building-windows-apps-from-non-windows-platforms) for details on non-Windows platforms)
    * - Linux: this option is not supported, as the dock/window list icon is set via
    *   [the `icon` option in the `BrowserWindow` constructor](https://electronjs.org/docs/api/browser-window/#new-browserwindowoptions).
@@ -447,7 +451,7 @@ export interface Options {
    * If the file extension is omitted, it is auto-completed to the correct extension based on the
    * platform, including when {@link platform |`platform: 'all'`} is in effect.
    */
-  icon?: string;
+  icon?: string | string[];
   /**
    * One or more additional [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions)
    * patterns which specify which files to ignore when copying files to create the app bundle(s). The

src/win32.ts

@@ -38,10 +38,13 @@ export class WindowsApp extends App {
     };
   }
 
-  async getIconPath() {
+  async getIconPath(): Promise<string | void> {
     if (!this.opts.icon) {
       return Promise.resolve();
     }
+    if (Array.isArray(this.opts.icon)) {
+      throw new Error('opts.path must be a single path on Windows');
+    }
 
     return this.normalizeIconExtension('.ico');
   }