From 06401ba425d28c0f992ec834105bbffa3c5dfb8f Mon Sep 17 00:00:00 2001 From: Timothy Lau Date: Fri, 6 Mar 2026 16:17:53 +0800 Subject: [PATCH 1/2] docs: enhance icon generation guide with detailed format requirements and macOS support --- guides/create-and-add-icons.md | 65 +++++++++++++++++++++++++++++----- 1 file changed, 57 insertions(+), 8 deletions(-) diff --git a/guides/create-and-add-icons.md b/guides/create-and-add-icons.md index 9d40887..4be666b 100644 --- a/guides/create-and-add-icons.md +++ b/guides/create-and-add-icons.md @@ -8,7 +8,7 @@ description: >- ## Generating an icon -Generating your icon can be done using various conversion tools found online. It is recommended to start with a 1024x1024px image before converting it to various sizes. +Generating your icon can be done using various conversion tools found online. It is recommended to start with a 1024x1024px image before converting it to the formats required by each platform. ### Supporting higher pixel densities @@ -33,19 +33,23 @@ The following suffixes for DPI are also supported: The recommended file formats and icon sizes for each platform are as follows: -| Operating system | Format | Size | -| ---------------- | ------- | ---------------------------------------------- | -| macOS | `.icns` | 512x512 pixels (1024x1024 for Retina displays) | -| Windows | `.ico` | 256x256 pixels | -| Linux | `.png` | 512x512 pixels | +| Operating system | Format | Size / notes | +| ---------------- | ------------------------ | ------------------------------------------------------------------------------------------------- | +| macOS | `.icns`, optionally `.icon` | Use a 1024x1024 source image. Keep an `.icns` file for compatibility, and add an Icon Composer `.icon` file for macOS 26+. | +| Windows | `.ico` | 256x256 pixels | +| Linux | `.png` | 512x512 pixels | {% hint style="warning" %} On Windows, ensure that your `.ico` file is exported from an image editor that supports the format (such as [GIMP](https://www.gimp.org/)). Renaming a `.png` file into `.ico` will result in a `Fatal error: Unable to set icon` error. {% endhint %} +{% hint style="info" %} +`@electron/packager` supports macOS Icon Composer files as of [electron/packager#1806](https://github.com/electron/packager/pull/1806). To support both macOS 26+ and earlier releases, provide both an `.icns` file and a `.icon` file. +{% endhint %} + ## Setting the app icon -### Windows and macOS +### Windows Configuring the path to your icon can be done in your Forge configuration. @@ -62,7 +66,52 @@ module.exports = { {% endcode %} {% hint style="success" %} -Forge will automatically add the correct extension for each platform, so appending `.ico` or `.icns` to the path is not required. +When you provide a single icon path, Electron Packager will automatically add the correct platform extension, so appending `.ico` here is not required. +{% endhint %} + +After the config has been updated, build your project to generate your executable with the Make command. + +### macOS + +If you only need the traditional macOS icon format, you can continue to provide a single `icon` path in `packagerConfig`: + +{% code title="forge.config.js" %} +```javascript +module.exports = { + // ... + packagerConfig: { + icon: '/path/to/icon' // .icns will be inferred + } + // ... +}; +``` +{% endcode %} + +If you need one configuration that supports both macOS 26+ and earlier macOS releases, provide both an `.icns` file and an `.icon` file: + +{% code title="forge.config.js" %} +```javascript +module.exports = { + // ... + packagerConfig: { + icon: [ + '/path/to/icon.icns', + '/path/to/icon.icon' + ] + } + // ... +}; +``` +{% endcode %} + +Electron Packager will use the `.icns` file on macOS versions earlier than 26, and the `.icon` file on macOS 26 and later. + +{% hint style="warning" %} +Packaging a `.icon` file currently requires macOS 26 or later and Xcode 26 or later, because Electron Packager uses Apple's `actool` tool to compile the Icon Composer asset. +{% endhint %} + +{% hint style="info" %} +When you provide multiple macOS icon files, include the file extensions explicitly so Packager can distinguish the `.icns` and `.icon` inputs. {% endhint %} After the config has been updated, build your project to generate your executable with the Make command. From 7c61ed45ae11ab4a6dab97d5a84ad9251db5c35a Mon Sep 17 00:00:00 2001 From: Erick Zhao Date: Fri, 6 Mar 2026 19:35:19 -0800 Subject: [PATCH 2/2] small adjustments --- guides/create-and-add-icons.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/guides/create-and-add-icons.md b/guides/create-and-add-icons.md index 4be666b..a274093 100644 --- a/guides/create-and-add-icons.md +++ b/guides/create-and-add-icons.md @@ -33,18 +33,18 @@ The following suffixes for DPI are also supported: The recommended file formats and icon sizes for each platform are as follows: -| Operating system | Format | Size / notes | -| ---------------- | ------------------------ | ------------------------------------------------------------------------------------------------- | -| macOS | `.icns`, optionally `.icon` | Use a 1024x1024 source image. Keep an `.icns` file for compatibility, and add an Icon Composer `.icon` file for macOS 26+. | -| Windows | `.ico` | 256x256 pixels | -| Linux | `.png` | 512x512 pixels | +| Operating system | Format | Size / notes | +| ---------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------- | +| macOS | `.icns` (or `.icon`) | Use a 1024x1024 source image. Keep an `.icns` file for compatibility, and add an Icon Composer `.icon` file for macOS 26+. | +| Windows | `.ico` | 256x256 pixels | +| Linux | `.png` | 512x512 pixels | {% hint style="warning" %} On Windows, ensure that your `.ico` file is exported from an image editor that supports the format (such as [GIMP](https://www.gimp.org/)). Renaming a `.png` file into `.ico` will result in a `Fatal error: Unable to set icon` error. {% endhint %} {% hint style="info" %} -`@electron/packager` supports macOS Icon Composer files as of [electron/packager#1806](https://github.com/electron/packager/pull/1806). To support both macOS 26+ and earlier releases, provide both an `.icns` file and a `.icon` file. +`@electron/packager` supports macOS Icon Composer files as of [`@electron/packager` v18.4.0](https://github.com/electron/packager/releases/tag/v18.4.0). To support both macOS 26+ and earlier releases, provide both an `.icns` file and a `.icon` file. {% endhint %} ## Setting the app icon @@ -107,7 +107,7 @@ module.exports = { Electron Packager will use the `.icns` file on macOS versions earlier than 26, and the `.icon` file on macOS 26 and later. {% hint style="warning" %} -Packaging a `.icon` file currently requires macOS 26 or later and Xcode 26 or later, because Electron Packager uses Apple's `actool` tool to compile the Icon Composer asset. +Packaging an `.icon` file currently requires macOS 26 or later and Xcode 26 or later because Electron Packager uses Apple's `actool` tool to compile the Icon Composer asset. {% endhint %} {% hint style="info" %}