@todesktop/cli 1.12.5 → 1.13.0-0

package/README.md

@@ -26,19 +26,6 @@ npm install --location=global @todesktop/cli
 yarn global add @todesktop/cli
 ```
 
-Once installed, you can enable JSON validation and IntelliSense for your configuration files. To do so, please add the following to your VSCode/Cursor workspace settings:
-
-```json
-{
-  "json.schemas": [
-    {
-      "fileMatch": ["todesktop.json", "todesktop.*.json"],
-      "url": "./node_modules/@todesktop/cli/schemas/schema.json"
-    }
-  ]
-}
-```
-
 ## Get started
 
 You can use the ToDesktop CLI to work with an Electron application in 4 steps:
@@ -55,9 +42,10 @@ Create a `todesktop.json` file in the root of your Electron project.
 
 ```json
 {
+  "$schema": "https://unpkg.com/@todesktop/cli@1.12.5/schemas/schema.json",
+  "schemaVersion": 1
   "id": "your-todesktop-id",
   "icon": "./desktop-icon.png",
-  "schemaVersion": 1
 }
 ```
 
@@ -227,6 +215,31 @@ To avoid confusion, the following terms will be used throughout this file:
 
 - "Project root": this is the parent directory of your `todesktop.json`.
 
+### `$schema` - (optional) string
+
+
+
+Example: `https://unpkg.com/@todesktop/cli@1.12.5/schemas/schema.json`, `./node_modules/@todesktop/cli/schemas/schema.json`
+
+To enable JSON validation and IntelliSense for your `todesktop.json` file in compatible code editors, your editor needs to know where the schema file is located. You can add a `$schema` property to the top of your `todesktop.json` file, pointing to a version of the schema. This can be a local path or a hosted URL.
+
+- For example, if using a hosted version of the schema:
+  ```json
+  {
+    "$schema": "https://unpkg.com/@todesktop/cli@1.12.5/schemas/schema.json", // Example URL
+    "id": "your-todesktop-id"
+    // ... other configurations
+  }
+  ```
+- Or if ToDesktop CLI is installed locally, you can use a local path:
+  ```json
+  {
+    "$schema": "./node_modules/@todesktop/cli/schemas/schema.json",
+    "id": "your-todesktop-id"
+    // ... other configurations
+  }
+  ```
+
 ### `appFiles` - (optional) array of glob patterns
 
 Default: `["**"]`
@@ -263,9 +276,9 @@ We use the [fast-glob](https://www.npmjs.com/package/fast-glob) library under th
 
 ### `appId` - (optional) string
 
-Default: auto-generated.
+Default: auto-generated
 
-Example: `com.microsoft.word`.
+Example: `com.microsoft.word`
 
 Your application ID. Omit this unless you know what you're doing. It's used as the [CFBundleIdentifier](https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-102070) for MacOS and as the [Application User Model ID](<https://msdn.microsoft.com/en-us/library/windows/desktop/dd378459(v=vs.85).aspx>) for Windows.
 
@@ -273,9 +286,9 @@ WARNING: if you have deployed an application with ToDesktop and would like to ch
 
 ### `appPath` - (optional) string
 
-Default: `.`.
+Default: `.`
 
-Example: `./dist`.
+Example: `./dist`
 
 This is the path to your Electron application directory. Omit this unless your project setup is complicated. This is the directory that the CLI uploads.
 
@@ -289,21 +302,21 @@ Side note: if your `package.json` contains a `postinstall` script which referenc
 
 ### `appProtocolScheme` - (optional) string | string[]
 
-Default: no protocol scheme is registered.
+Default: no protocol scheme is registered
 
-Example: `word` or `[word, ...]`.
+Example: `word`, `["word", "excel"]`
 
 If you want to register a protocol for your application (e.g. `example://`) and or support deeplinking, you will need to use this option. If your desired protocol is `example://`, you would set `"appProtocolScheme": "example"`. NOTE: these features also require additional application logic.
 
 ### `asar` - (optional) boolean
 
-Default: true
+Default: `true`
 
 Whether to package your application's source code within an asar archive. You should only turn this off if you have a good reason to.
 
 ### `asarUnpack` - (optional) boolean or array of glob patterns
 
-Default: [`**/*.node`]
+Default: `["**/*.node"]`
 
 This option allows you to decide which files get unpacked from the asar archive. By default we unpack all native `*.node` files.
 
@@ -321,18 +334,20 @@ The build version. Maps to the CFBundleVersion on macOS, and FileVersion metadat
 
 Default: The `package.json` [productName](#recommendations-for-app-packagejson) / `name`.
 
-Example: `Copyright © 1995 Walt Disney`.
+Example: `Copyright © 1995 Walt Disney`
 
 The human-readable copyright line for the app.
 
 ### `dmg` - (optional) object
 
-#### `dmg.background` - (optional) string
+Options for customizing the macOS DMG (disk image) installer.
 
-Example: `./mac-dmg-background.tiff`.
+#### `dmg.background` - (optional) string
 
 Default: `undefined` (if `undefined` then we use [this template](https://i.imgur.com/PUQIhvv.png)).
 
+Example: `./mac-dmg-background.tiff`
+
 The path to the DMG installer's background image. It must be a `.tiff` file. The resolution of this file determines the resolution of the installer window. Typically, backgrounds are 540x380.
 
 You can generate a retina tiff background from png files using the following command:
@@ -343,21 +358,27 @@ tiffutil -cathidpicheck background.png background@2x.png -out background.tiff
 
 #### `dmg.backgroundColor` - (optional) string
 
+Default: `#ffffff`
+
 The background color (accepts css colors). Defaults to "`#ffffff`" (white) if no background image.
 
 #### `dmg.iconSize` - (optional) number
 
+Default: `80`
+
 The size of all the icons inside the DMG. Defaults to `80`.
 
 #### `dmg.iconTextSize` - (optional) number
 
+Default: `12`
+
 The size of all the icon texts inside the DMG. Defaults to `12`.
 
 #### `dmg.title` - (optional) string
 
-The title of the produced DMG, which will be shown when mounted (volume name). Macro `${productName}`, `${version}` and `${name}` are supported.
+Default: ${productName} ${version}
 
-Defaults to "`${productName} ${version}`".
+The title of the produced DMG, which will be shown when mounted (volume name). Macro `${productName}`, `${version}` and `${name}` are supported.
 
 #### `dmg.contents` - (optional) Array of objects
 
@@ -399,9 +420,7 @@ The DMG windows position and size. In most cases, you will only want to specify
 
 ### `extends` - (optional) string
 
-Default: `null`.
-
-Example: `./todesktop.staging.json`.
+Example: `./todesktop.staging.json`
 
 This is the path to a base configuration file. This is especially useful for configuration sharing between staging and production builds. The base configuration file can be a relative path from the project root or an absolute path.
 
@@ -409,7 +428,7 @@ For more information about how to create a staging version of your app see: [How
 
 ### `extraContentFiles` - (optional) array of objects
 
-Default: `[]`.
+Default: `[]`
 
 This option allows you specify files to be copied into the application's content directory (`Contents` for MacOS, root directory for Linux and Windows).
 
@@ -447,7 +466,7 @@ The version of Electron to use. In most cases you should not specify an `electro
 
 ### `extraResources` - (optional) array of objects
 
-Default: `[]`.
+Default: `[]`
 
 Example:
 
@@ -477,14 +496,13 @@ Example:
 ```
 
 - `ext` String | String[] - The extension (minus the leading period). e.g. png.
-- `name` String - The name. e.g. PNG. Defaults to value of `ext`.
+- `name` String -  The name. e.g. PNG. Defaults to value of `ext`.
 - `description` String - windows-only. The description.
-- `icon` String - macOS and windows. Icon file name without extension. It points
-  to ico file for Windows and icns for macOS. For example, if the `icon` value is `"icons/py"` then it will look for both `"icons/py.ico"` and `"icons/py.icns"` in your project directory.
+- `icon` String - macOS and windows. Icon file name without extension. It points to ico file for Windows and icns for macOS. For example, if the `icon` value is `"icons/py"` then it will look for both `"icons/py.ico"` and `"icons/py.icns"` in your project directory.
 - `mimeType` String - linux-only. The mime-type.
-- `role` = `Editor` String - macOS-only. The app's role with respect to the type. The value can be `Editor`, `Viewer`, `Shell`, or `None`. Corresponds to `CFBundleTypeRole`.
+- `role` = `Default: `Editor`` String - macOS-only. The app's role with respect to the type. The value can be `Editor`, `Viewer`, `Shell`, or `None`. Corresponds to `CFBundleTypeRole`.
 - `isPackage` Boolean - macOS-only. Whether the document is distributed as a bundle. If set to true, the bundle directory is treated as a file. Corresponds to `LSTypeIsPackage`.
-- `rank` = `Default` String macOS-only. Determines how Launch Services ranks this app among the apps that declare themselves editors or viewers of files of this type. The possible values are: `Owner` (this app is the primary creator of files of this type), `Default` (this app is an opener of files of this type; this value is also used if no rank is specified), `Alternate` (this app is a secondary viewer of files of this type), and `None` (this app is never selected to open files of this type, but it accepts drops of files of this type).
+- `rank` = `Default: `Default`` String - macOS-only. Determines how Launch Services ranks this app among the apps that declare themselves editors or viewers of files of this type. The possible values are: `Owner` (this app is the primary creator of files of this type), `Default` (this app is an opener of files of this type; this value is also used if no rank is specified), `Alternate` (this app is a secondary viewer of files of this type), and `None` (this app is never selected to open files of this type, but it accepts drops of files of this type).
 
 ### `filesForDistribution` - (optional) array of glob patterns
 
@@ -510,7 +528,7 @@ The following are always excluded if they exist:
 
 ### `icon` - string
 
-Example: `./appIcon.png`.
+Example: `./appIcon.png`
 
 The path to your application's desktop icon. It must be an ICNS or PNG.
 
@@ -520,42 +538,42 @@ Note: to ensure the icon is never missing (e.g. this happens sometimes in Ubuntu
 
 Example: `2005223bd1nqpl7`
 
-Your ToDesktop application ID. This is used to identify your app. This would have been generated when you first created your ToDesktop application via the web interface:
+Your ToDesktop application ID. This is used to identify your app. This would have been generated when you first created your ToDesktop application via the web interface.
 
 ![ToDesktop ID](https://firebasestorage.googleapis.com/v0/b/todesktop-prod1.appspot.com/o/assets%2Ftodesktop-id.png?alt=media&token=5985e731-76c4-43e8-bbfb-bd708b7cfffd)
 
 ### `linux` - (optional) object
 
-Default: We have good default settings for Linux.
-
-Example: `{ "category": "Utility"`.
+Example: `{ "category": "Utility"}`
 
 This object contains some options that only apply to the building & releasing for Linux.
 
-#### `linux.category` - (optional) string
+Default: We have good default settings for Linux.
 
-Default: undefined
+#### `linux.category` - (optional) string
 
-Example: `Utility`.
+Example: `Utility`
 
 The [application category](https://specifications.freedesktop.org/menu-spec/latest/apa.html#main-category-registry).
 
-#### `linux.icon` - (optional) string
+Default: undefined
 
-Example: `./linux-icon.png`.
+#### `linux.icon` - (optional) string
 
-Default: The root [`icon`](#icon---string) is used.
+Example: `./linux-icon.png`
 
 The path to your application's Linux desktop icon. It must be an ICNS or PNG.
 
+Default: The root [`icon`](#icon---string) is used.
+
 Note: to ensure the icon is never missing (e.g. this happens sometimes in Ubuntu), set the [`icon` option](https://www.electronjs.org/docs/api/browser-window#new-browserwindowoptions) when creating your `BrowserWindow`s.
 
 #### `linux.imageVersion` - (optional) string
 
-Example: `0.1.0`
-
 Default: `0.0.11`
 
+Example: `0.1.0`
+
 The version of the Linux image that ToDesktop should use to build your app.
 
 Linux Changelog:
@@ -580,21 +598,24 @@ Whether to include **all** of the submodules node_modules directories
 ### `mac` - (optional) object
 
 Default: We have good default settings for Mac.
-Example: `{ "entitlements": "./entitlements.mac.plist" }`.
+
+Example: `{ "entitlements": "./entitlements.mac.plist" }`
 
 This object contains some options that only apply to the building & releasing for MacOS.
 
 #### `mac.additionalBinariesToSign` - (optional) array of strings
 
 Default: `[]`
-Example: `["./node_modules/example-package/example-file"]`.
+
+Example: `["./node_modules/example-package/example-file"]`
 
 Paths of any extra binaries that need to be signed. These could be files in your own app code or `node_modules`.
 
 #### `mac.category` - (optional) string
 
 Default: undefined
-Example: `public.app-category.productivity`.
+
+Example: `public.app-category.productivity`
 
 The application category type, as shown in the Finder via _View -> Arrange by Application Category_ when viewing the Applications directory.
 
@@ -605,90 +626,100 @@ Valid values are listed in [Apple's documentation](https://developer.apple.com/l
 #### `mac.entitlements` - (optional) string
 
 Default: A sane minimal entitlements file we've put together.
-Example: `./entitlements.mac.plist`.
+
+Example: `./entitlements.mac.plist`
 
 The path to an entitlements file for signing your application. It must be a plist file.
 
 #### `mac.entitlementsInherit` - (optional) string
 
 Default: No entitlements file is provided by default.
-Example: `./entitlementsInherit.mac.plist`.
+
+Example: `./entitlementsInherit.mac.plist`
 
 The path to a child entitlements file for signing your application. It must be a plist file.
 
 #### `mac.extendInfo` - (optional) object
 
-Default: `{}`.
-Example: `{ "NSUserNotificationAlertStyle": "alert" }`.
+Default: `{}`
+
+Example: `{ "NSUserNotificationAlertStyle": "alert" }`
 
 Extra entries for `Info.plist`.
 
 #### `mac.icon` - (optional) string
 
-Example: `./mac-icon.png`.
-
-Default: The root [`icon`](#icon---string) is used.
+Example: `./mac-icon.png`
 
 The path to your application's Mac desktop icon. It must be an ICNS or PNG.
 
+Default: The root [`icon`](#icon---string) is used.
+
 #### `mac.requirements` - (optional) string
 
-Example: `./requirements.txt`.
 Default: No requirements file is used by default.
 
+Example: `./requirements.txt`
+
 The path to the [requirements file](https://developer.apple.com/library/archive/documentation/Security/Conceptual/CodeSigningGuide/RequirementLang/RequirementLang.html) used when signing your application.
 
 ### `mas` - (optional) object
 
-Default: We use default development settings for Mac App Store.
-Example: `{ "type": "development" }`.
+Example: `{ "type": "development" }`
 
 This object contains options that only apply to building the application for Mac App Store.
 
+Default: We use default development settings for Mac App Store.
+
 #### `mas.entitlements` - (optional) string
 
 Default: No entitlements file is provided by default.
-Example: `./entitlements.mas.plist`.
+
+Example: `./entitlements.mas.plist`
 
 The path to an entitlements file for signing your application. It must be a plist file.
 
 #### `mas.entitlementsInherit` - (optional) string
 
 Default: No entitlements file is provided by default.
-Example: `./entitlementsInherit.mas.plist`.
+
+Example: `./entitlementsInherit.mas.plist`
 
 The path to a child entitlements file for signing your application. It must be a plist file.
 
 #### `mas.provisioningProfile` - (optional) string
 
 Default: No provisioning profile is used by default.
-Example: `./mas.provisionprofile`.
+
+Example: `./mas.provisionprofile`
 
 The path to a provisioning profile for authorizing your application.
 
 #### `mas.type` - (optional) string
 
-Default: `"development"`
-Example: `"distribution"`.
+Default: `development`
+
+Example: `distribution`
 
 Whether to sign app for development or for distribution.
 
 ### `mas.x64ArchFiles` - (optional) string
 
 Default: not defined
-Example: `"Contents/Resources/foobar/**"`
+
+Example: `Contents/Resources/foobar/**`
 
 Minimatch pattern of paths that are allowed to be x64 binaries in both ASAR files.
 
 ### `nodeVersion` - string
 
-Example: `18.12.1`.
+Example: `18.12.1`
 
 The version of Node.js that ToDesktop should use to build your app.
 
 ### `npmVersion` - string
 
-Example: `9.8.1`.
+Example: `9.8.1`
 
 The version of NPM that ToDesktop should use for installation.
 
@@ -696,6 +727,8 @@ The version of NPM that ToDesktop should use for installation.
 
 Default: `{}`
 
+If you want to override the default `package.json` configuration, use the `packageJson` property. For example, you can use this to override the `productName` or `version` properties.
+
 Example:
 
 ```js
@@ -709,8 +742,6 @@ Example:
 }
 ```
 
-If you want to override the default `package.json` configuration, use the `packageJson` property. For example, you can use this to override the `productName` or `version` properties.
-
 You can also set the version of a `dependency` (or `devDependency`), such as Electron Builder, to `null`. This will remove Electron Builder from the effective `package.json` that ToDesktop will use.
 
 ```js
@@ -732,33 +763,33 @@ The package manager to use when installing dependencies. Valid values are `npm`,
 
 ### `pnpmVersion` - string
 
-Example: `8.10.5`.
+Example: `8.10.5`
 
 The version of pnpm that ToDesktop should use for installation.
 
 ### `rebuildLibrary` - (optional) string
 
-Default: `app-builder`.
+Default: `app-builder`
 
 The library that ToDesktop should use for rebuilding native modules. Valid values are `app-builder` or `@electron/rebuild`.
 
 ### `schemaVersion` - number
 
-Example: `1`.
+Example: `1`
 
 This is the `todesktop.json` schema version. This must be `1`.
 
 ### `snap` - (optional) object
 
-Example: `{ "confinement": "classic", "grade": "devel" }`.
+Example: `{ "confinement": "classic", "grade": "devel" }`
 
 This object contains some options that only apply to the building for the [Snap Store](https://snapcraft.io/store).
 
 #### `snap.after` - (optional) array of strings
 
-Default: `["desktop-gtk2"]`.
+Default: `["desktop-gtk2"]`
 
-Example: `["launch-scripts"]`.
+Example: `["launch-scripts"]`
 
 Ensures that all the part names listed are staged before the app part begins its [lifecycle](https://snapcraft.io/docs/parts-lifecycle#heading--steps).
 
@@ -766,79 +797,79 @@ Ensures that all the part names listed are staged before the app part begins its
 
 Default: See [snap.ts](https://github.com/electron-userland/electron-builder/blob/master/packages/app-builder-lib/templates/snap/snapcraft.yaml#L29).
 
-Example: `["-usr/lib/python*"]`.
+Example: `["-usr/lib/python*"]`
 
 Specifies which files from the app part to stage and which to exclude. Individual files, directories, wildcards, globstars, and exclusions are accepted. See [Snapcraft filesets](https://snapcraft.io/docs/snapcraft-filesets) to learn more about the format.
 
 #### `snap.assumes` - (optional) string or array of strings
 
-Default: `undefined`.
+Default: `undefined`
 
-Example: `snapd2.38`.
+Example: `snapd2.38`
 
 The list of features that must be supported by the core in order for this snap to install. To learn more, see the [Snapcraft docs](https://snapcraft.io/docs/snapcraft-top-level-metadata#heading--assumes).
 
 #### `snap.autoStart` - (optional) boolean
 
-Default: `false`.
+Default: `false`
 
-Example: `true`.
+Example: `true`
 
 Whether or not the snap should automatically start on login.
 
 #### `snap.base` - (optional) string
 
-Default: `core18`.
+Default: `core18`
 
-Example: `core20`.
+Example: `core20`
 
 The base snap to use for building this snap.
 
 #### `snap.buildPackages` - (optional) array of strings
 
-Default: `[]`.
+Default: `[]`
 
-Example: `["libssl-dev", "libssh-dev", "libncursesw5-dev"]`.
+Example: `["libssl-dev", "libssh-dev", "libncursesw5-dev"]`
 
 The list of debian packages needs to be installed for building this snap.
 
 #### `snap.confinement` - (optional) string
 
-Default: `strict`.
+Default: `strict`
 
-Example: `classic`.
+Example: `classic`
 
 The type of [confinement](https://snapcraft.io/docs/reference/confinement) supported by the snap. `devmode`, `strict`, or `classic`.
 
 #### `snap.environment` - (optional) object
 
-Default: `{"TMPDIR": "$XDG_RUNTIME_DIR"}`.
+Default: `{"TMPDIR":"$XDG_RUNTIME_DIR"}`
 
-Example: `{"TMPDIR": "$XDG_RUNTIME_DIR"}`.
+Example: `{"TMPDIR": "$XDG_RUNTIME_DIR"}`
 
 The custom environment. If you set this, it will be merged with the default.
 
 #### `snap.grade` - (optional) string
 
-Default: `stable`.
+Default: `stable`
 
-Example: `devel`.
+Example: `devel`
 
 The quality grade of the snap. It can be either `devel` (i.e. a development version of the snap, so not to be published to the "stable" or "candidate" channels) or `stable` (i.e. a stable release or release candidate, which can be released to all channels).
 
 #### `snap.layout` - (optional) object
 
-Default: `undefined`.
+Default: `undefined`
 
-Example: `{ "/var/lib/foo": { bind: "$SNAP_DATA/var/lib/foo" } }`.
+Example: `{ "/var/lib/foo": { "bind": "$SNAP_DATA/var/lib/foo" } }`
 
 Specifies any files to make accessible from locations such as `/usr`, `/var`, and `/etc`. See [snap layouts](https://snapcraft.io/docs/snap-layouts) to learn more.
 
 #### `snap.plugs` - (optional) array containing strings and or objects
 
-Default: `["desktop", "desktop-legacy", "home", "x11", "unity7", "browser-support", "network", "gsettings", "pulseaudio", "opengl"]`.
+Default: `["desktop","desktop-legacy","home","x11","unity7","browser-support","network","gsettings","pulseaudio","opengl"]`
 
-Example: `[ "default", { "browser-sandbox": { "interface": "browser-support", "allow-sandbox": true } }, "another-simple-plug-name" ]`.
+Example: `[ "default", { "browser-sandbox": { "interface": "browser-support", "allow-sandbox": true } }, "another-simple-plug-name" ]`
 
 The list of [plugs](https://snapcraft.io/docs/reference/interfaces). If list contains `default`, it will be replaced with the default list, so, `["default", "foo"]` can be used to add a custom plug `foo` in addition to the default list.
 
@@ -858,9 +889,9 @@ Additional attributes can be specified using object instead of just name of plug
 
 #### `snap.stagePackages` - (optional) array of strings
 
-Default: `["libasound2", "libgconf2-4", "libnotify4", "libnspr4", "libnss3", "libpcre3", "libpulse0", "libxss1", "libxtst6"]`.
+Default: `["libasound2","libgconf2-4","libnotify4","libnspr4","libnss3","libpcre3","libpulse0","libxss1","libxtst6"]`
 
-Example: `["default", "depends"]`.
+Example: `["default", "depends"]`
 
 The list of Ubuntu packages to use that are needed to support the app part creation. Like `depends` for deb. If list contains `default`, it will be replaced with the default list, so, `["default", "foo"]` can be used to add custom package `foo` in addition to the defaults.
 
@@ -868,50 +899,56 @@ The list of Ubuntu packages to use that are needed to support the app part creat
 
 Default: The [productName](#recommendations-for-app-packagejson).
 
-Example: `The super cat generator`.
+Example: `The super cat generator`
 
 A sentence summarising the snap. Max len. 78 characters, describing the snap in short and simple terms.
 
 #### `snap.useTemplateApp` - (optional) boolean
 
-Default: `true` if `stagePackages` is not specified.
+Default: true if `stagePackages` is not specified.
 
-Example: `false`.
+Example: `false`
 
 Whether to use a template snap.
 
 ### `updateUrlBase` - (optional) string
 
 Default: ToDesktop's auto-update URL.
-Example: `https://example.com/updates`.
+
+Example: `https://example.com/updates`
 
 The URL to check for updates. You should only set this if you want to use your own self-hosted update server instead of ToDesktop's built-in update service. See https://www.github.com/ToDesktop/self-hosted for more information.
 
 ### `uploadSizeLimit` - (optional) number
 
-Default: `20`.
-Example: `35`.
+Default: `20`
+
+Example: `35`
 
 The max upload size (in MB). Before uploading your files to our servers, we check that the total file size is less than this number. If you are accidentally including unneccesary files in your app, check out the `appPath` and `appFiles` options.
 
 ### `windows` - (optional) object
 
-Default: We have good default settings for Windows.
-
-Example: `{ "icon": "./icon.ico" }`.
+Example: `{ "icon": "./icon.ico" }`
 
 This object contains some options that only apply to the building & releasing for Windows.
 
+Default: We have good default settings for Windows.
+
 #### `windows.icon` - (optional) string
 
-Example: `./icon.ico`.
-
-Default: The root [`icon`](#icon---string) is used.
+Example: `./icon.ico`
 
 The path to your application's Windows desktop icon. It must be an ICO, ICNS, or PNG.
 
+Default: The root [`icon`](#icon---string) is used.
+
 #### `windows.nsisCustomBinary` - (optional) object
 
+Default: `undefined`
+
+Allows you to provide your own makensis, such as one with support for debug logging via LogSet and LogText. (Logging also requires option debugLogging = true). It's not recommended to use it for production build.
+
 Example:
 
 ```json
@@ -922,10 +959,6 @@ Example:
 }
 ```
 
-Default: `undefined`.
-
-Allows you to provide your own makensis, such as one with support for debug logging via LogSet and LogText. (Logging also requires option debugLogging = true). It's not recommended to use it for production build.
-
 Example of NSIS script which enables install logging:
 
 ```nsis
@@ -937,26 +970,80 @@ Example of NSIS script which enables install logging:
 
 #### `windows.nsisInclude` - (optional) string
 
-Example: `build/installer.nsh`.
+Default: `undefined`
 
-Default: `undefined`.
+Example: `build/installer.nsh`
 
 The path to NSIS script to customize installer.
 
 #### `windows.publisherName` - (optional) array of strings
 
-Example: `["ABC Limited"]`.
-
 Default: Default to the common name from your code signing certificate.
 
+Example: `["ABC Limited"]`
+
 The publisher name, exactly as in your code signing certificate. Several names can be provided. Defaults to common name from your code signing certificate. You should typically not include this property in your configuration unless you wish to transition to a new certificate in the future.
 
 ### `appBuilderLibVersion` - (optional) string
 
-Example: `22.14.13`.
+Example: `22.14.13`
 
 The version of app-builder-lib that ToDesktop should use for building your app. This can be useful if you need to use a specific version that includes certain features or fixes.
 
+### `platformOverrides` - (optional) object
+
+Default: `{}`
+
+This option allows you to specify platform-specific configurations for Windows, macOS, and Linux builds. Most top-level configuration fields available in `todesktop.json` can be overridden within the `windows`, `mac`, or `linux` objects under `platformOverrides`.
+
+Example:
+
+```json
+{
+  "appId": "myapp.global.id",
+  "platformOverrides": {
+    "windows": {
+      "appId": "myapp.windows.id",
+      "copyright": "Copyright © My Company (Windows)"
+    },
+    "mac": {
+      "appId": "myapp.mac.id",
+      "mac": {
+        "category": "public.app-category.developer-tools"
+      }
+    },
+    "linux": {
+      "copyright": "Copyright © My Company (Linux)"
+    }
+  }
+}
+```
+
+When a build is performed for a specific platform (e.g., Windows), the ToDesktop CLI will first take the global configuration value for a field. If that same field is defined within `platformOverrides.windows`, the platform-specific value will be used instead.
+
+In the example above:
+
+- For Windows builds:
+  - `appId` will be `myapp.windows.id`.
+  - `copyright` will be `Copyright © My Company (Windows)`.
+- For macOS builds:
+  - `appId` will be `myapp.mac.id`.
+  - The `mac.category` will be `public.app-category.developer-tools`.
+- For Linux builds:
+  - `appId` will remain `myapp.global.id` (as it's not overridden for Linux).
+  - `copyright` will be `Copyright © My Company (Linux)`.
+- For any other properties not specified in the platform override, the global value will be used.
+
+This is particularly useful for settings like `appId`, `copyright`, or platform-specific configurations within the `windows`, `mac`, or `linux` blocks (e.g., `mac.category`, `windows.icon`).
+
+The fields that **cannot** be overridden using `platformOverrides` are:
+
+- `id` (the ToDesktop application ID)
+- `icon` (the main application icon, though platform-specific icons like `windows.icon` or `mac.icon` _can_ be overridden)
+- `schemaVersion`
+- `extends`
+- `platformOverrides` itself
+
 ## Build lifecycle hooks (package.json scripts)
 
 Sometimes you want to do something before or during the build process. For example, you might want to run a script before the build starts, or you might want to run a script after the files have been packaged. Our lifecycle hooks provide a way to do this.
@@ -1336,7 +1423,7 @@ Now, when we build your app on ToDesktop servers, it will also run your custom `
 
 ### v1.7.4
 
-- Fix: Linux/Windows platform links no longer have mac/zip/\[arch\] added to the end of the download URL
+- Fix: Linux/Windows platform links no longer have mac/zip/[arch] added to the end of the download URL
 
 ### v1.7.3