app-builder-lib Module

Core library for building Electron applications

The app-builder-lib module is the core library used by electron-builder. It provides the Packager class and all configuration interfaces.

Installation

npm install app-builder-lib --save-dev

Main Function

build()

Builds the application with the specified options.

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

Source: packages/app-builder-lib/src/index.ts:82

options · PackagerOptions & PublishOptions · required

Build and publish options.

packager · Packager

Optional Packager instance. If not provided, a new one is created.

Returns: Promise<Array<string>> - Paths to built artifacts.

Packager Class

The main packager class that orchestrates the build process.

Constructor

new Packager(options: PackagerOptions)

options · PackagerOptions · required

Packager configuration options.

Properties

appInfo · AppInfo

Application metadata and information.

config · Configuration

Resolved build configuration.

projectDir · string

The project directory path.

cancellationToken · CancellationToken

Token for cancelling the build process.

Methods

build()

Executes the build process.

build(): Promise<BuildResult>

Returns: Promise<BuildResult> - Build result with artifact paths and configuration.

BuildResult Interface

The result of a build operation.

interface BuildResult {
  readonly artifactPaths: Array<string>
  readonly configuration: Configuration
  readonly platformToTargets: Map<Platform, Map<string, Target>>
}

artifactPaths · Array<string>

Paths to all built artifacts.

configuration · Configuration

The configuration used for the build.

platformToTargets · Map<Platform, Map<string, Target>>

Map of platforms to their targets.

Platform Packagers

Platform-specific packager classes.

MacPackager

Packager for macOS applications.

class MacPackager extends PlatformPackager<MacConfiguration>

Methods:

• pack(outDir: string, arch: Arch, targets: Array<Target>): Promise<void>
• sign(path: string, options?: CustomMacSignOptions): Promise<void>

WinPackager

Packager for Windows applications.

class WinPackager extends PlatformPackager<WindowsConfiguration>

Methods:

• pack(outDir: string, arch: Arch, targets: Array<Target>): Promise<void>
• sign(file: string): Promise<void>

LinuxPackager

Packager for Linux applications.

class LinuxPackager extends PlatformPackager<LinuxConfiguration>

Methods:

• pack(outDir: string, arch: Arch, targets: Array<Target>): Promise<void>

AppInfo Class

Provides application information from package.json and configuration.

Properties

name · string

Application name from package.json.

productName · string

Product name (defaults to name if not specified).

version · string

Application version.

buildVersion · string

Build version (may include build number).

description · string

Application description.

copyright · string

Copyright string.

productFilename · string

Safe filename for the product.

Target Class

Abstract base class for build targets.

abstract class Target {
  abstract readonly outDir: string
  abstract readonly options: TargetSpecificOptions | null
  
  constructor(
    readonly name: string,
    readonly isAsyncSupported: boolean = true
  )
  
  abstract build(appOutDir: string, arch: Arch): Promise<any>
  async finishBuild(): Promise<any>
}

Source: packages/app-builder-lib/src/core.ts:74

name · string

Target name (e.g., “dmg”, “nsis”).

outDir · string

Output directory for this target.

options · TargetSpecificOptions | null

Target-specific options.

Core Enums and Types

CompressionLevel

type CompressionLevel = "store" | "normal" | "maximum"

• store - No compression (fastest)
• normal - Standard compression (default)
• maximum - Maximum compression (slowest)

DIR_TARGET

const DIR_TARGET = "dir"

Special target name for unpacked directory output.

DEFAULT_TARGET

const DEFAULT_TARGET = "default"

Indicates platform default targets should be used.

Utility Functions

checkBuildRequestOptions()

Validates build options.

function checkBuildRequestOptions(options: PackagerOptions & PublishOptions): void

Throws InvalidConfigurationError if unknown options are provided.

Exported Modules

Configuration

• Configuration - Main configuration
• CommonConfiguration - Common config options
• Hooks - Lifecycle hooks
• MetadataDirectories - Directory configuration
• ToolsetConfig - Toolset versions

Platform Options

• MacConfiguration, DmgOptions, PkgOptions, MasConfiguration
• WindowsConfiguration, NsisOptions, AppXOptions, MsiOptions
• LinuxConfiguration, DebOptions, AppImageOptions, SnapOptions

Build Options

• PlatformSpecificBuildOptions
• FilesBuildOptions
• AsarOptions
• FileSet

Metadata

• Metadata - package.json metadata
• AuthorMetadata - Author info
• RepositoryInfo - Repository info

Protocols and Associations

• Protocol - URL protocol schemes
• FileAssociation - File associations

Code Signing

• WindowsSignOptions
• CustomWindowsSign, CustomWindowsSignTaskConfiguration
• CustomMacSign, CustomMacSignOptions
• CertificateFromStoreInfo, FileCodeSigningInfo

Electron Options

• ElectronDownloadOptions
• ElectronBrandingOptions

Events

• ArtifactCreated
• ArtifactBuildStarted

Contexts

• BeforeBuildContext
• BeforePackContext
• AfterPackContext
• AfterExtractContext
• PackContext

Forge Integration

buildForge()

Builds using Electron Forge maker configuration.

function buildForge(
  forgeOptions: ForgeOptions,
  options?: PackagerOptions
): Promise<Array<string>>

Import Examples

CommonJS

const { build, Packager, Platform } = require("app-builder-lib")

ES Modules / TypeScript

import { build, Packager, Platform } from "app-builder-lib"
import type { Configuration, PackagerOptions, BuildResult } from "app-builder-lib"

See Also

• Configuration Interface
• PackagerOptions Interface
• Platform-Specific Options
• electron-builder Module