or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

build-system.mdcode-signing.mdconfiguration.mdindex.mdlinux-packaging.mdmacos-packaging.mdplatform-targets.mdpublishing.mdwindows-packaging.md
tile.json

tessl/npm-electron-builder

A complete solution to package and build a ready for distribution Electron app for MacOS, Windows and Linux with auto update support out of the box

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/electron-builder@26.0.x

To install, run

npx @tessl/cli install tessl/npm-electron-builder@26.0.0

index.mddocs/

Electron Builder

Electron Builder is a complete solution to package and build ready-for-distribution Electron applications for macOS, Windows, and Linux with built-in auto-update support. It provides a comprehensive build pipeline from source code to distributable installers, handling code signing, native dependencies, and publishing to various platforms.

Package Information

  • Package Name: electron-builder
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install --save-dev electron-builder

Core Imports

import { 
  build, 
  publish, 
  createTargets, 
  Platform, 
  Arch,
  buildForge,
  CancellationToken,
  getArchSuffix,
  archFromString,
  log
} from "electron-builder";

For CommonJS:

const { 
  build, 
  publish, 
  createTargets, 
  Platform, 
  Arch,
  buildForge,
  CancellationToken,
  getArchSuffix,
  archFromString,
  log 
} = require("electron-builder");

Configuration and type imports:

import type {
  Configuration,
  PackagerOptions,
  PublishOptions,
  TargetConfiguration,
  MacConfiguration,
  WindowsConfiguration,
  LinuxConfiguration,
  BuildResult
} from "electron-builder";

Basic Usage

import { build, Platform } from "electron-builder";

// Basic build for current platform
await build({
  targets: Platform.current().createTarget(),
  config: {
    appId: "com.example.myapp",
    productName: "My App",
    directories: {
      output: "dist"
    }
  }
});

// Cross-platform build
await build({
  targets: new Map([
    [Platform.MAC, new Map([[Arch.x64, ["dmg", "zip"]]])],
    [Platform.WINDOWS, new Map([[Arch.x64, ["nsis", "portable"]]])],
    [Platform.LINUX, new Map([[Arch.x64, ["AppImage", "deb"]]])]
  ])
});

Architecture

Electron Builder is structured around several key components:

  • Core Build System: build() function orchestrates the entire packaging process
  • Platform Packagers: Specialized classes (MacPackager, WinPackager, LinuxPackager) handle platform-specific logic
  • Target System: Modular target classes generate specific output formats (DMG, NSIS, AppImage, etc.)
  • Configuration System: Flexible configuration merging from package.json, config files, and CLI options
  • Publishing System: PublishManager handles artifact upload to various distribution platforms
  • Code Signing: Integrated signing for Windows, macOS with certificate management
  • Dependency Management: Automatic native dependency rebuilding and ASAR packaging

Capabilities

Build System

Core build functionality for packaging Electron applications into distributable formats. Handles the complete build pipeline from source to installer.

function build(options: PackagerOptions & PublishOptions, packager?: Packager): Promise<Array<string>>;

interface PackagerOptions {
  targets?: TargetMap;
  mac?: Array<string>;
  win?: Array<string>;
  linux?: Array<string>;
  config?: Configuration | string | null;
  projectDir?: string | null;
  prepackaged?: string | null;
}

interface PublishOptions {
  publish?: PublishPolicy | null;
}

type PublishPolicy = "onTag" | "onTagOrDraft" | "always" | "never";

Build System

Electron Forge Integration

Integration with Electron Forge for hybrid build workflows.

function buildForge(forgeOptions: ForgeOptions): Promise<Array<string>>;

interface ForgeOptions {
  /** Forge configuration object */
  config?: any;
  /** Output directory for build artifacts */
  dir?: string;
  /** Enable interactive mode for user prompts */
  interactive?: boolean;
  /** Custom packager options */
  packagerOptions?: PackagerOptions;
  /** Publishing configuration */
  publishOptions?: PublishOptions;
}

Platform and Target Management

Platform abstraction and target configuration system for cross-platform builds. Manages architecture and output format combinations.

class Platform {
  static MAC: Platform;
  static WINDOWS: Platform;
  static LINUX: Platform;
  static current(): Platform;
  createTarget(type?: string | Array<string> | null, archs?: Array<Arch>): TargetMap;
}

enum Arch {
  ia32 = "ia32",
  x64 = "x64",
  armv7l = "armv7l", 
  arm64 = "arm64",
  universal = "universal"
}

function createTargets(platforms: Array<Platform>, type?: string | null, arch?: string | null): TargetMap;

Platform and Targets

Configuration

Comprehensive configuration system for customizing build behavior, output formats, and platform-specific options.

interface Configuration extends PlatformSpecificBuildOptions {
  appId?: string | null;
  productName?: string | null;
  directories?: MetadataDirectories | null;
  files?: FileSet | null;
  extraFiles?: Array<FileSet> | FileSet | null;
  extraResources?: Array<FileSet> | FileSet | null;
  mac?: MacConfiguration | null;
  win?: WindowsConfiguration | null;
  linux?: LinuxConfiguration | null;
  publish?: Array<PublishConfiguration> | PublishConfiguration | null;
}

interface MetadataDirectories {
  buildResources?: string | null;
  output?: string | null;
  app?: string | null;
}

Configuration

macOS Packaging

macOS-specific packaging options including DMG creation, code signing, notarization, and App Store distribution.

interface MacConfiguration extends PlatformSpecificBuildOptions {
  identity?: string | null;
  icon?: string | null;
  entitlements?: string | null;
  entitlementsInherit?: string | null;
  provisioningProfile?: string | null;
  bundleVersion?: string | null;
  helperBundleId?: string | null;
  helperRendererBundleId?: string | null;
  helperPluginBundleId?: string | null;
  helperGPUBundleId?: string | null;
  helperEHBundleId?: string | null;
  type?: "distribution" | "development" | null;
  extendInfo?: any;
  binaries?: Array<string> | null;
  minimumSystemVersion?: string | null;
  requirements?: string | null;
  electronLanguages?: Array<string> | string;
  strictVerify?: boolean | string | Array<string>;
  gatekeeperAssess?: boolean;
  darkModeSupport?: boolean;
  mergeASARs?: boolean;
  x64ArchFiles?: string;
  singleArchFiles?: string;
}

interface DmgOptions {
  background?: string | null;
  backgroundColor?: string | null;
  icon?: string | null;
  iconSize?: number | null;
  iconTextSize?: number | null;
  title?: string | null;
  contents?: Array<DmgContent>;
  format?: "UDZO" | "UDBZ" | "ULFO" | "UDRO" | "UDCO" | "UDRW" | "UDTO" | "UDSP" | "UDSB" | "UFBI";
  window?: DmgWindow | null;
  internetEnabled?: boolean;
  sign?: boolean;
  writeUpdateInfo?: boolean;
}

macOS Packaging

Windows Packaging

Windows-specific packaging including NSIS installers, MSI packages, code signing, and Squirrel.Windows auto-updater.

interface WindowsConfiguration extends PlatformSpecificBuildOptions {
  target?: TargetConfiguration | Array<TargetConfiguration | string> | string | null;
  icon?: string | null;
  legalTrademarks?: string | null;
  signtoolOptions?: Array<string> | null;
  sign?: string | WindowsSignOptions | null;
  certificateFile?: string | null;
  certificatePassword?: string | null;
  certificateSha1?: string | null;
  certificateSubjectName?: string | null;
  rfc3161TimeStampServer?: string | null;
  timeStampServer?: string | null;
  publisherName?: string | Array<string> | null;
  verifyUpdateCodeSignature?: boolean;
  requestedExecutionLevel?: "asInvoker" | "highestAvailable" | "requireAdministrator" | null;
  applicationManifest?: string | null;
  extraFiles?: Array<FileSet> | FileSet | null;
  extraResources?: Array<FileSet> | FileSet | null;
}

interface NsisOptions {
  oneClick?: boolean;
  perMachine?: boolean;
  allowElevation?: boolean;
  allowToChangeInstallationDirectory?: boolean;
  installerIcon?: string | null;
  uninstallerIcon?: string | null;
  installerHeader?: string | null;
  installerHeaderIcon?: string | null;
  installerSidebar?: string | null;
  uninstallerSidebar?: string | null;
  installerLanguages?: Array<string> | string | null;
  language?: string | null;
  multiLanguageInstaller?: boolean;
  packElevateHelper?: boolean;
  preCompressedFileExtensions?: Array<string> | null;
  unicode?: boolean;
  guid?: string | null;
  warningsAsErrors?: boolean;
}

Windows Packaging

Linux Packaging

Linux-specific packaging including AppImage, Snap, Flatpak, and traditional package formats (deb, rpm, tar).

interface LinuxConfiguration extends PlatformSpecificBuildOptions {
  target?: TargetConfiguration | Array<TargetConfiguration | string> | string | null;
  maintainer?: string | null;
  vendor?: string | null;
  icon?: string | null;
  packageCategory?: string | null;
  description?: string | null;
  synopsis?: string | null;
  priority?: string | null;
  mimeTypes?: Array<string> | null;
  desktop?: LinuxDesktopFile | null;
  executableName?: string | null;
}

interface AppImageOptions {
  license?: string | null;
  desktop?: LinuxDesktopFile | null;
  category?: string | null;
  systemIntegration?: "ask" | "doNotAsk";
}

interface SnapOptions {
  buildPackages?: Array<string> | null;
  stagePackages?: Array<string> | null;
  plugs?: Array<string> | PlugDescriptor | null;
  slots?: Array<SlotDescriptor> | null;
  after?: Array<string> | null;
  usesStagedKernel?: boolean;
  buildEnvironment?: Array<string> | null;
  grade?: "devel" | "stable" | null;
  assumes?: Array<string> | null;
  architectures?: Array<string> | null;
  layout?: any;
  title?: string | null;
  autoStart?: boolean;
  summary?: string | null;
  description?: string | null;
  base?: string | null;
  confinement?: "devmode" | "strict" | "classic" | null;
}

Linux Packaging

Publishing System

Artifact publishing to various distribution platforms including GitHub Releases, S3, and custom servers with auto-update support.

function publish(args: {
  files: string[];
  version: string | undefined;
  configurationFilePath: string | undefined;
  policy: PublishPolicy;
}): Promise<any>;

function publishArtifactsWithOptions(
  uploadOptions: Array<{file: string; arch: string | null}>,
  buildVersion?: string,
  configurationFilePath?: string,
  publishConfiguration?: PublishConfiguration,
  publishOptions?: PublishOptions
): Promise<any>;

class PublishManager {
  constructor(packager: Packager, options: PublishOptions, cancellationToken?: CancellationToken);
  getGlobalPublishConfigurations(): Promise<Array<PublishConfiguration> | null>;
  scheduleUpload(publishConfig: PublishConfiguration, uploadTask: UploadTask, appInfo: AppInfo): Promise<any>;
  awaitTasks(): Promise<Array<string>>;
  cancelTasks(): void;
}

Publishing System

Code Signing

Integrated code signing for Windows and macOS with certificate management, timestamping, and validation.

interface WindowsSignOptions {
  certificateFile?: string | null;
  certificatePassword?: string | null;
  certificateSha1?: string | null;
  certificateSubjectName?: string | null;
  signtoolOptions?: Array<string> | null;
  rfc3161TimeStampServer?: string | null;
  timeStampServer?: string | null;
  additionalCertificateFile?: string | null;
}

interface CustomWindowsSign {
  (configuration: CustomWindowsSignTaskConfiguration, packager: WinPackager): Promise<any>;
}

interface CustomMacSign {
  (configuration: CustomMacSignOptions, packager: MacPackager): Promise<any>;
}

Code Signing

CLI Commands

Build Command

electron-builder [build-options]
electron-builder --mac --win --linux
electron-builder --publish=onTagOrDraft
electron-builder --config path/to/config.json
electron-builder --projectDir /path/to/project

Publishing Command

electron-builder publish --files="dist/*.dmg,dist/*.exe"
electron-builder publish --publish=always

Dependency Installation

electron-builder install-app-deps
electron-builder install-app-deps --platform=win32 --arch=x64

Self-Signed Certificate Creation

electron-builder create-self-signed-cert --publisher="My Company"

Development Mode

electron-builder start

Utility Functions

Architecture Utilities

Architecture detection and manipulation utilities from builder-util.

/**
 * Convert architecture string to Arch enum
 * @param name - Architecture name (ia32, x64, armv7l, arm64, universal)
 * @returns Corresponding Arch enum value
 */
function archFromString(name: string): Arch;

/**
 * Get architecture suffix for file naming
 * @param arch - Target architecture
 * @param defaultArch - Default architecture to omit suffix for
 * @returns Architecture suffix string or empty string
 */
function getArchSuffix(arch: Arch, defaultArch?: Arch): string;

Logging Utilities

Integrated logging system for build processes.

/**
 * Global logger instance for electron-builder operations
 */
const log: Logger;

interface Logger {
  info(message: string | any, ...args: any[]): void;
  warn(message: string | any, ...args: any[]): void;
  error(message: string | any, ...args: any[]): void;
  debug(message: string | any, ...args: any[]): void;
}

## Types and Interfaces

```typescript { .api }
interface BuildResult {
  artifactPaths: Array<string>;
  platformToTargets: Map<Platform, Map<String, Target>>;
  outDir: string;
  configuration: Configuration;
}

interface TargetConfiguration {
  target: string;
  arch?: Array<Arch> | string | Arch | null;
}

interface FileSet {
  from?: string;
  to?: string;
  filter?: Array<string> | string;
}

interface ProgressInfo {
  total: number;
  delta: number;
  transferred: number;
  percent: number;
  bytesPerSecond: number;
}

class CancellationToken {
  readonly isCancellationRequested: boolean;
  readonly cancelled: boolean;
  cancel(): void;
  createChild(): CancellationToken;
  createPromise<T>(executor: (resolve: (value?: T) => void, reject: (reason?: any) => void, onCancel: (callback: () => void) => void) => void): Promise<T>;
}

This comprehensive API enables building production-ready Electron applications with professional installers, automatic updates, and cross-platform distribution capabilities.