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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Configuration

Name: tessl/npm-electron-builder
Author: tessl

Comprehensive configuration system for customizing Electron Builder behavior, output formats, and platform-specific options. Configuration can be specified through package.json, dedicated config files, or programmatically.

Capabilities

Main Configuration Interface

Central configuration interface extending platform-specific build options.

/**
 * Main electron-builder configuration
 */
interface Configuration extends PlatformSpecificBuildOptions {
  /** Application identifier (reverse DNS notation, e.g., com.example.myapp) */
  appId?: string | null;
  /** Product name for display purposes */
  productName?: string | null;
  /** Directory structure configuration */
  directories?: MetadataDirectories | null;
  /** File inclusion/exclusion patterns */
  files?: FileSet | null;
  /** Extra files to copy to build directory */
  extraFiles?: Array<FileSet> | FileSet | null;
  /** Extra resources to include in app bundle */
  extraResources?: Array<FileSet> | FileSet | null;
  /** macOS-specific configuration */
  mac?: MacConfiguration | null;
  /** Windows-specific configuration */
  win?: WindowsConfiguration | null;
  /** Linux-specific configuration */
  linux?: LinuxConfiguration | null;
  /** Publishing configuration */
  publish?: Array<PublishConfiguration> | PublishConfiguration | null;
  /** Build hooks for custom logic */
  beforeBuild?: Hook | null;
  beforePack?: Hook | null;
  afterPack?: Hook | null;
  afterAllArtifactBuild?: Hook | null;
  /** Extends configuration from another file */
  extends?: string | null;
  /** Include/exclude patterns for packing app directory */
  asarUnpack?: Array<string> | string | null;
  /** File associations for the application */
  fileAssociations?: Array<FileAssociation> | FileAssociation | null;
  /** URL protocols handled by the application */
  protocols?: Array<Protocol> | Protocol | null;
  /** Force code signing (macOS/Windows) */
  forceCodeSigning?: boolean;
}

Usage Examples:

import { Configuration } from "electron-builder";

const config: Configuration = {
  appId: "com.example.myapp",
  productName: "My Application",
  directories: {
    output: "dist",
    buildResources: "build"
  },
  files: [
    "build/**/*",
    "node_modules/**/*",
    "!node_modules/.bin/**/*"
  ],
  mac: {
    category: "public.app-category.productivity",
    icon: "build/icon.icns"
  },
  win: {
    icon: "build/icon.ico"
  },
  linux: {
    icon: "build/icon.png"
  }
};

Directory Configuration

Specify custom directory structure for build process.

/**
 * Directory structure configuration
 */
interface MetadataDirectories {
  /** Build resources directory (default: "build") */
  buildResources?: string | null;
  /** Output directory for built packages (default: "dist") */
  output?: string | null;
  /** App directory relative to project root (default: current directory) */
  app?: string | null;
}

Platform-Specific Build Options

Base options shared across all platforms.

/**
 * Base platform-specific build options
 */
interface PlatformSpecificBuildOptions {
  /** Artifact file name template */
  artifactName?: string | null;
  /** Executable name (without extension) */
  executableName?: string | null;
  /** Compression level for packages */
  compression?: CompressionLevel | null;
  /** Files to include/exclude from build */
  files?: Array<FileSet> | FileSet | string | null;
  /** Extra files to copy to build directory */
  extraFiles?: Array<FileSet> | FileSet | null;
  /** Extra resources for app bundle */
  extraResources?: Array<FileSet> | FileSet | null;
  /** ASAR archive options */
  asar?: AsarOptions | boolean | null;
  /** Target configurations for this platform */
  target?: TargetConfigType | null;
  /** Application icon path */
  icon?: string | null;
}

/**
 * File inclusion/exclusion pattern
 */
interface FileSet {
  /** Source path or pattern */
  from?: string;
  /** Destination path */
  to?: string;
  /** Inclusion/exclusion filters */
  filter?: Array<string> | string;
}

/**
 * ASAR archive configuration
 */
interface AsarOptions {
  /** Smart unpacking based on file types */
  smartUnpack?: boolean;
  /** Unpack specified files/patterns */
  unpack?: string | null;
  /** Unpack directories matching patterns */
  unpackDir?: string | null;
}

Usage Examples:

import { FileSet, AsarOptions } from "electron-builder";

// File set configuration
const fileConfig: FileSet = {
  from: "resources",
  to: "app/resources",
  filter: ["**/*", "!**/*.log"]
};

// ASAR configuration  
const asarConfig: AsarOptions = {
  smartUnpack: true,
  unpack: "*.{node,dll}",
  unpackDir: "native_modules"
};

// Platform configuration
const config = {
  files: [
    "build/**/*",
    { from: "assets", to: "resources" },
    "!node_modules/.bin/**/*"
  ],
  asar: asarConfig
};

Application Metadata

Metadata configuration for application identification and display.

/**
 * Application metadata from package.json
 */
interface Metadata {
  /** Package name */
  readonly name?: string;
  /** Package version */
  readonly version?: string;
  /** Package description */
  readonly description?: string;
  /** Package main entry point */
  readonly main?: string | null;
  /** Package author */
  readonly author?: AuthorMetadata | string;
  /** Package homepage URL */
  readonly homepage?: string;
  /** Package repository information */
  readonly repository?: string | RepositoryInfo | null;
}

/**
 * Author metadata structure
 */
interface AuthorMetadata {
  readonly name: string;
  readonly email?: string;
  readonly url?: string;
}

/**
 * Repository information
 */
interface RepositoryInfo {
  readonly type?: string;
  readonly url: string;
  readonly directory?: string;
}

File Associations

Configure file type associations for the application.

/**
 * File type association configuration
 */
interface FileAssociation {
  /** File extension (without dot) */
  ext: string | Array<string>;
  /** Association name/description */
  name?: string;
  /** Description of the file type */
  description?: string;
  /** MIME type */
  mimeType?: string;
  /** Icon for associated files */
  icon?: string;
  /** Verb for the association (Windows) */
  role?: string;
  /** Whether files open in existing instance */
  isPackage?: boolean;
}

Usage Examples:

import { FileAssociation } from "electron-builder";

const associations: Array<FileAssociation> = [
  {
    ext: "myapp",
    name: "My App Document",
    description: "My App Document File",
    icon: "build/file-icon.ico",
    role: "Editor"
  },
  {
    ext: ["json", "txt"],
    name: "Text Document",
    description: "Plain text or JSON file"
  }
];

URL Protocols

Configure custom URL protocol handlers.

/**
 * URL protocol handler configuration
 */
interface Protocol {
  /** Protocol name (without ://) */
  name: string;
  /** Protocol display name */
  description?: string;
  /** Protocol schemes */
  schemes: Array<string>;
  /** Protocol role (macOS) */
  role?: "Editor" | "Viewer" | "Shell" | "None";
}

Usage Examples:

import { Protocol } from "electron-builder";

const protocols: Array<Protocol> = [
  {
    name: "myapp-protocol",
    description: "My App Custom Protocol",
    schemes: ["myapp"],
    role: "Editor"
  }
];

Build Hooks

Custom functions executed at specific points in the build process.

/**
 * Build hook function signature
 */
type Hook = string | ((context: HookContext) => Promise<any>);

/**
 * Hook execution context
 */
interface HookContext {
  /** Application information */
  appInfo: AppInfo;
  /** Platform being built */
  platform: Platform;
  /** Architecture being built */
  arch: Arch;
  /** Packager instance */
  packager: Packager;
  /** Electron version */
  electronVersion: string;
}

/**
 * After-pack context with additional information
 */
interface AfterPackContext extends HookContext {
  /** Path to packaged app directory */
  appOutDir: string;
  /** Platform packager instance */
  platformPackager: PlatformPackager;
}

/**
 * Before-pack context
 */
interface BeforePackContext extends HookContext {
  /** Platform packager instance */
  platformPackager: PlatformPackager;
}

Usage Examples:

import { Configuration, AfterPackContext } from "electron-builder";

const config: Configuration = {
  // Hook as function
  afterPack: async (context: AfterPackContext) => {
    console.log(`Packaged app for ${context.platform.name}`);
    // Custom post-processing logic
  },
  
  // Hook as script path
  beforeBuild: "./scripts/before-build.js",
  
  // Hook for final artifact processing
  afterAllArtifactBuild: async (buildResult) => {
    console.log("All artifacts built:", buildResult.artifactPaths);
    return []; // Return additional artifacts if needed
  }
};

Release Information

Configuration for release notes and update information.

/**
 * Release information configuration
 */
interface ReleaseInfo {
  /** Release name/title */
  releaseName?: string;
  /** Release notes */
  releaseNotes?: string;
  /** Path to release notes file */
  releaseNotesFile?: string;
  /** Release date */
  releaseDate?: string;
}

Configuration Loading

Configuration is loaded automatically from multiple sources in order of precedence:

CLI options - Highest priority
Environment variables - Prefixed with ELECTRON_BUILDER_
Config files - electron-builder.yml, electron-builder.json, etc.
package.json - build property
Default values - Built-in defaults

Configuration file examples:

// electron-builder.json
{
  "appId": "com.example.myapp",
  "productName": "My App",
  "directories": {
    "output": "dist"
  },
  "files": [
    "build/**/*",
    "node_modules/**/*"
  ],
  "mac": {
    "icon": "build/icon.icns"
  }
}

# electron-builder.yml
appId: com.example.myapp
productName: My App
directories:
  output: dist
files:
  - build/**/*
  - node_modules/**/*
mac:
  icon: build/icon.icns

The configuration system provides comprehensive control over all aspects of the build process while maintaining backward compatibility and sensible defaults.

Install with Tessl CLI