chore: update docs to include more interfaces and change changset-cli release configuration (#8467)

Author: mmaietta

.changeset/config.json

@@ -17,5 +17,8 @@
   "access": "public",
   "baseBranch": "master",
   "updateInternalDependencies": "patch",
-  "ignore": ["@electron-builder/test"]
+  "ignore": ["@electron-builder/test"],
+  "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
+    "onlyUpdatePeerDependentsWhenOutOfRange": true
+  }
 }

.changeset/sharp-sloths-teach.md

@@ -0,0 +1,5 @@
+---
+"app-builder-lib": patch
+---
+
+chore: update docs to include more interfaces and release configuration

docs/api/electron-builder.md

@@ -106,6 +106,7 @@ Developer API only. See [Configuration](../configuration/configuration.md) for u
 <li><a href="#BeforeBuildContext"><code>.BeforeBuildContext</code></a></li>
 <li><a href="#BuildResult"><code>.BuildResult</code></a></li>
 <li><a href="#CertificateFromStoreInfo"><code>.CertificateFromStoreInfo</code></a></li>
+<li><a href="#CustomNsisBinary"><code>.CustomNsisBinary</code></a></li>
 <li><a href="#FileCodeSigningInfo"><code>.FileCodeSigningInfo</code></a></li>
 <li><a href="#Framework"><code>.Framework</code></a>
 <ul>
@@ -314,6 +315,16 @@ Developer API only. See [Configuration](../configuration/configuration.md) for u
 <li><strong><code id="CertificateFromStoreInfo-store">store</code></strong> String</li>
 <li><strong><code id="CertificateFromStoreInfo-isLocalMachineStore">isLocalMachineStore</code></strong> Boolean</li>
 </ul>
+<p><a name="CustomNsisBinary"></a></p>
+<h2 id="customnsisbinary"><code>CustomNsisBinary</code></h2>
+<p><strong>Kind</strong>: interface of <a href="#module_app-builder-lib"><code>app-builder-lib</code></a><br/>
+<strong>Properties</strong></p>
+<ul>
+<li><strong><code id="CustomNsisBinary-url">url</code></strong> = <code>https://github.com/electron-userland/electron-builder-binaries/releases/download</code> String | “undefined”</li>
+<li><code id="CustomNsisBinary-checksum">checksum</code> = <code>VKMiizYdmNdJOWpRGz4trl4lD++BvYP2irAXpMilheUP0pc93iKlWAoP843Vlraj8YG19CVn0j+dCo/hURz9+Q==</code> String | “undefined”</li>
+<li><code id="CustomNsisBinary-version">version</code> = <code>3.0.4.1</code> String | “undefined”</li>
+<li><code id="CustomNsisBinary-debugLogging">debugLogging</code> Boolean | “undefined” - Whether or not to enable NSIS logging for debugging. Note: Requires a debug-enabled NSIS build. electron-builder’s included <code>makensis</code> does not natively support debug-enabled NSIS installers currently, you must supply your own via <code>customNsisBinary?: CustomNsisBinary</code> In your custom nsis scripts, you can leverage this functionality via <code>LogSet</code> and <code>LogText</code></li>
+</ul>
 <p><a name="FileCodeSigningInfo"></a></p>
 <h2 id="filecodesigninginfo"><code>FileCodeSigningInfo</code></h2>
 <p><strong>Kind</strong>: interface of <a href="#module_app-builder-lib"><code>app-builder-lib</code></a><br/>

docs/generated/NsisOptions.md

@@ -65,7 +65,7 @@
 <li><code id="NsisOptions-unicode">unicode</code> = <code>true</code> Boolean - Whether to create <a href="http://nsis.sourceforge.net/Docs/Chapter1.html#intro-unicode">Unicode installer</a>.</li>
 <li><code id="NsisOptions-guid">guid</code> String | “undefined” - See <a href="../configuration/nsis#guid-vs-application-name">GUID vs Application Name</a>.</li>
 <li><code id="NsisOptions-warningsAsErrors">warningsAsErrors</code> = <code>true</code> Boolean - If <code>warningsAsErrors</code> is <code>true</code> (default): NSIS will treat warnings as errors. If <code>warningsAsErrors</code> is <code>false</code>: NSIS will allow warnings.</li>
-<li><code id="NsisOptions-customNsisBinary">customNsisBinary</code> module:app-builder-lib/out/targets/nsis/nsisOptions.CustomNsisBinary | “undefined” - Allows you to provide your own <code>makensis</code>, such as one with support for debug logging via LogSet and LogText. (Logging also requires option <code>debugLogging = true</code>)</li>
+<li><code id="NsisOptions-customNsisBinary">customNsisBinary</code> <a href="#CustomNsisBinary">CustomNsisBinary</a> | “undefined” - Allows you to provide your own <code>makensis</code>, such as one with support for debug logging via LogSet and LogText. (Logging also requires option <code>debugLogging = true</code>)</li>
 <li><code id="NsisOptions-runAfterFinish">runAfterFinish</code> = <code>true</code> Boolean - Whether to run the installed application after finish. For assisted installer corresponding checkbox will be removed.</li>
 </ul>
 <hr>
@@ -75,5 +75,13 @@
 <li><code id="NsisOptions-menuCategory">menuCategory</code> = <code>false</code> Boolean | String - Whether to create submenu for start menu shortcut and program files directory. If <code>true</code>, company name will be used. Or string value.</li>
 <li><code id="NsisOptions-shortcutName">shortcutName</code> String | “undefined” - The name that will be used for all shortcuts. Defaults to the application name.</li>
 </ul>
+<h2 id="customnsisbinary">CustomNsisBinary</h2>
+<p>undefined</p>
+<ul>
+<li><strong><code id="CustomNsisBinary-url">url</code></strong> = <code>https://github.com/electron-userland/electron-builder-binaries/releases/download</code> String | “undefined”</li>
+<li><code id="CustomNsisBinary-checksum">checksum</code> = <code>VKMiizYdmNdJOWpRGz4trl4lD++BvYP2irAXpMilheUP0pc93iKlWAoP843Vlraj8YG19CVn0j+dCo/hURz9+Q==</code> String | “undefined”</li>
+<li><code id="CustomNsisBinary-version">version</code> = <code>3.0.4.1</code> String | “undefined”</li>
+<li><code id="CustomNsisBinary-debugLogging">debugLogging</code> Boolean | “undefined” - Whether or not to enable NSIS logging for debugging. Note: Requires a debug-enabled NSIS build. electron-builder’s included <code>makensis</code> does not natively support debug-enabled NSIS installers currently, you must supply your own via <code>customNsisBinary?: CustomNsisBinary</code> In your custom nsis scripts, you can leverage this functionality via <code>LogSet</code> and <code>LogText</code></li>
+</ul>
 
 <!-- end of generated block -->

packages/app-builder-lib/src/configuration.ts

@@ -162,7 +162,7 @@ export interface Configuration extends PlatformSpecificBuildOptions {
   /**
    * Returns the path to custom Electron build (e.g. `~/electron/out/R`). Zip files must follow the pattern `electron-v${version}-${platformName}-${arch}.zip`, otherwise it will be assumed to be an unpacked Electron app directory
    */
-  readonly electronDist?: string | ((options: PrepareApplicationStageDirectoryOptions) => string)
+  readonly electronDist?: string | CustomElectronDistributable
 
   /**
    * The [electron-download](https://github.com/electron-userland/electron-download#usage) options.
@@ -218,52 +218,53 @@ export interface Configuration extends PlatformSpecificBuildOptions {
   /**
    * The function (or path to file or module id) to be [run before pack](#beforepack)
    */
-  readonly beforePack?: ((context: BeforePackContext) => Promise<any> | any) | string | null
+  readonly beforePack?: Hook<BeforePackContext, any> | string | null
 
   /**
    * The function (or path to file or module id) to be [run after the prebuilt Electron binary has been extracted to the output directory](#afterextract)
    */
-  readonly afterExtract?: ((context: AfterExtractContext) => Promise<any> | any) | string | null
+  readonly afterExtract?: Hook<AfterExtractContext, any> | string | null
 
   /**
    * The function (or path to file or module id) to be [run after pack](#afterpack) (but before pack into distributable format and sign).
    */
-  readonly afterPack?: ((context: AfterPackContext) => Promise<any> | any) | string | null
+  readonly afterPack?: Hook<AfterPackContext, any> | string | null
+
   /**
    * The function (or path to file or module id) to be [run after pack and sign](#aftersign) (but before pack into distributable format).
    */
-  readonly afterSign?: ((context: AfterPackContext) => Promise<any> | any) | string | null
+  readonly afterSign?: Hook<AfterPackContext, any> | string | null
 
   /**
    * The function (or path to file or module id) to be run on artifact build start.
    */
-  readonly artifactBuildStarted?: ((context: ArtifactBuildStarted) => Promise<any> | any) | string | null
+  readonly artifactBuildStarted?: Hook<ArtifactBuildStarted, any> | string | null
   /**
    * The function (or path to file or module id) to be run on artifact build completed.
    */
-  readonly artifactBuildCompleted?: ((context: ArtifactCreated) => Promise<any> | any) | string | null
+  readonly artifactBuildCompleted?: Hook<ArtifactCreated, any> | string | null
   /**
    * The function (or path to file or module id) to be [run after all artifacts are build](#afterAllArtifactBuild).
    */
-  readonly afterAllArtifactBuild?: ((context: BuildResult) => Promise<Array<string>> | Array<string>) | string | null
+  readonly afterAllArtifactBuild?: Hook<BuildResult, Array<string>> | string | null
   /**
    * MSI project created on disk - not packed into .msi package yet.
    */
-  readonly msiProjectCreated?: ((path: string) => Promise<any> | any) | string | null
+  readonly msiProjectCreated?: Hook<string, any> | string | null
   /**
    * Appx manifest created on disk - not packed into .appx package yet.
    */
-  readonly appxManifestCreated?: ((path: string) => Promise<any> | any) | string | null
+  readonly appxManifestCreated?: Hook<string, any> | string | null
   /**
    * The function (or path to file or module id) to be [run on each node module](#onnodemodulefile) file. Returning `true`/`false` will determine whether to force include or to use the default copier logic
    */
-  readonly onNodeModuleFile?: ((path: string) => void | boolean) | string | null
+  readonly onNodeModuleFile?: Hook<string, void | boolean> | string | null
   /**
    * The function (or path to file or module id) to be run before dependencies are installed or rebuilt. Works when `npmRebuild` is set to `true`. Resolving to `false` will skip dependencies install or rebuild.
    *
    * If provided and `node_modules` are missing, it will not invoke production dependencies check.
    */
-  readonly beforeBuild?: ((context: BeforeBuildContext) => Promise<any>) | string | null
+  readonly beforeBuild?: Hook<BeforeBuildContext, boolean | void> | string | null
 
   /**
    * Whether to include PDB files.
@@ -324,3 +325,7 @@ export interface MetadataDirectories {
    */
   readonly app?: string | null
 }
+
+export type CustomElectronDistributable = (options: PrepareApplicationStageDirectoryOptions) => string
+
+export type Hook<T, V> = (contextOrPath: T) => Promise<V> | V

packages/app-builder-lib/src/index.ts

@@ -21,7 +21,7 @@ export {
   CompressionLevel,
 } from "./core"
 export { getArchSuffix, Arch, archFromString } from "builder-util"
-export { Configuration, AfterPackContext, MetadataDirectories } from "./configuration"
+export { Configuration, AfterPackContext, MetadataDirectories, BeforePackContext, AfterExtractContext, CustomElectronDistributable, Hook } from "./configuration"
 export { ElectronBrandingOptions, ElectronDownloadOptions, ElectronPlatformName } from "./electron/ElectronFramework"
 export { PlatformSpecificBuildOptions, AsarOptions, FileSet, Protocol, ReleaseInfo } from "./options/PlatformSpecificBuildOptions"
 export { FileAssociation } from "./options/FileAssociation"
@@ -32,7 +32,7 @@ export { AppXOptions } from "./options/AppXOptions"
 export { MsiOptions } from "./options/MsiOptions"
 export { MsiWrappedOptions } from "./options/MsiWrappedOptions"
 export { CommonWindowsInstallerConfiguration } from "./options/CommonWindowsInstallerConfiguration"
-export { NsisOptions, NsisWebOptions, PortableOptions, CommonNsisOptions } from "./targets/nsis/nsisOptions"
+export { NsisOptions, NsisWebOptions, PortableOptions, CommonNsisOptions, CustomNsisBinary } from "./targets/nsis/nsisOptions"
 export { LinuxConfiguration, DebOptions, CommonLinuxOptions, LinuxTargetSpecificOptions, AppImageOptions, FlatpakOptions } from "./options/linuxOptions"
 export { SnapOptions, PlugDescriptor, SlotDescriptor } from "./options/SnapOptions"
 export { Metadata, AuthorMetadata, RepositoryInfo } from "./options/metadata"

packages/app-builder-lib/src/targets/nsis/nsisOptions.ts

@@ -1,7 +1,7 @@
 import { TargetSpecificOptions } from "../../core"
 import { CommonWindowsInstallerConfiguration } from "../.."
 
-interface CustomNsisBinary {
+export interface CustomNsisBinary {
   /**
    * @default https://github.com/electron-userland/electron-builder-binaries/releases/download
    */

scripts/jsdoc2md2html.js

@@ -242,7 +242,9 @@ async function render2(files, jsdoc2MdOptions) {
     new Page("generated/LinuxTargetSpecificOptions.md", "LinuxTargetSpecificOptions"),
     new Page("generated/PlatformSpecificBuildOptions.md", "PlatformSpecificBuildOptions"),
     new Page("generated/Metadata.md", "Metadata"),
-    new Page("generated/NsisOptions.md", "NsisOptions"),
+    new Page("generated/NsisOptions.md", "NsisOptions", {
+      "CustomNsisBinary": ""
+    }),
     new Page("generated/TargetSpecificOptions.md", "TargetSpecificOptions"),
   ]
 

test/snapshots/globTest.js.snap

@@ -9715,6 +9715,14 @@ Object {
             "package.json": Object {
               "size": "<size>",
             },
+            "script": Object {
+              "files": Object {
+                "cli.js": Object {
+                  "executable": true,
+                  "size": "<size>",
+                },
+              },
+            },
             "src": Object {
               "files": Object {
                 "ua-parser.js": Object {