Building the app

gSubs uses electron-builder to package the application for different platforms. This guide covers building the app for production releases.

Build configuration

The build configuration is defined in electron-builder.yml at the root of the project:

appId: com.cholaware.gsubs
productName: gSubs
copyright: Copyright © 2020 Cholaware

Platform-specific settings

Windows
macOS
Linux

win:
  target: nsis
  icon: build/icon.ico
  publish:
    - provider: github
nsis:
  perMachine: true

Target: NSIS installer (Windows)
Icon: Uses build/icon.ico
Installation: Per-machine installation (requires admin)
Publishing: Configured for GitHub Releases

dmg:
  contents:
    - x: 110
      y: 150
    - x: 400
      y: 150
      type: link
      path: /Applications

Target: DMG disk image
Layout: Custom positioning for app icon and Applications folder link

linux:
  category: Utility
  target:
    - AppImage
    - deb
    - rpm

Category: Utility application
Targets: AppImage (universal), deb (Debian/Ubuntu), rpm (Fedora/RHEL)

Build scripts

The package.json includes several build scripts:

{
  "scripts": {
    "pack": "build --dir",
    "dist:win": "build -w --config",
    "dist:mac": "build -m --config",
    "dist:linux": "build -l --config"
  }
}

Available commands

npm run pack

Builds the app without packaging into an installer.

npm run pack

Output: Unpacked application in dist/ directory (faster for testing)Use case: Testing the built app without creating installers

npm run dist:win

Builds a Windows installer.

npm run dist:win

Output:

dist/gSubs Setup X.X.X.exe - NSIS installer
dist/win-unpacked/ - Unpacked application

Requirements: Can be run on Windows, macOS, or Linux (using Wine)

npm run dist:mac

Builds a macOS disk image.

npm run dist:mac

Output:

dist/gSubs-X.X.X.dmg - macOS disk image
dist/mac/gSubs.app - Application bundle

Requirements: Must be run on macOS (code signing requires macOS)

npm run dist:linux

Builds Linux packages.

npm run dist:linux

Output:

dist/gSubs-X.X.X.AppImage - Universal Linux package
dist/gsubs_X.X.X_amd64.deb - Debian package
dist/gsubs-X.X.X.x86_64.rpm - RPM package

Requirements: Preferably run on Linux (can run on other platforms with limitations)

Building for all platforms

To build for multiple platforms at once, you can modify the build command. However, note that:

The original README mentions changing the dist script to build -wlm --config, but this has been split into separate scripts for better control and platform-specific builds.

If you want to build for all platforms in one command:

{
  "scripts": {
    "dist:all": "build -wml --config"
  }
}

Then run:

npm run dist:all

Cross-platform builds have limitations. For best results:

Build Windows on Windows or use CI/CD
Build macOS on macOS (required for code signing)
Build Linux on Linux or macOS

Build process

Prepare the build

Ensure all changes are committed and the version number in package.json is updated:

{
  "name": "gsubs",
  "version": "1.0.3"
}

Install dependencies

Make sure all dependencies are installed:

npm install

Run the build

Execute the appropriate build command for your target platform:

npm run dist:win

Verify the output

Check the dist/ directory for the generated installers and packages.

ls -la dist/

Build artifacts

After building, you’ll find these files in the dist/ directory:

Platform	File	Description
Windows	`gSubs Setup X.X.X.exe`	NSIS installer
macOS	`gSubs-X.X.X.dmg`	Disk image
Linux	`gSubs-X.X.X.AppImage`	Universal Linux package
Linux	`gsubs_X.X.X_amd64.deb`	Debian/Ubuntu package
Linux	`gsubs-X.X.X.x86_64.rpm`	Fedora/RHEL package

Code signing

The current configuration does not include code signing. For production releases, you should add code signing certificates.

Windows code signing

Add to electron-builder.yml:

win:
  certificateFile: path/to/certificate.pfx
  certificatePassword: ${CERTIFICATE_PASSWORD}

macOS code signing

Add to electron-builder.yml:

mac:
  identity: "Developer ID Application: Your Name (XXXXXXXXXX)"

Publishing

The Windows configuration includes GitHub publishing:

win:
  publish:
    - provider: github

To publish a release:

export GH_TOKEN="your_github_token"
npm run dist:win -- --publish always

This will:

Build the app
Create a draft release on GitHub
Upload the installer as a release asset

Troubleshooting

Build fails on native modules

Rebuild native modules for the correct Electron version:

npm run postinstall

Out of memory errors

Increase Node.js memory limit:

export NODE_OPTIONS=--max_old_space_size=4096
npm run dist:win

Missing build directory

Ensure the build/ directory exists with platform icons:

build/icon.ico (Windows)
build/icon.icns (macOS)
build/icon.png (Linux)

Next steps

Contributing

Learn how to contribute your changes

Architecture

Understand the codebase structure

Contributing

​Build configuration

​Platform-specific settings

​Build scripts

​Available commands

​Building for all platforms

​Build process

​Build artifacts

​Code signing

​Windows code signing

​macOS code signing

​Publishing

​Troubleshooting

​Build fails on native modules

​Out of memory errors

​Missing build directory

​Next steps

Contributing

Architecture

Build docs developers (and LLMs) love

Build configuration

Platform-specific settings

Build scripts

Available commands

Building for all platforms

Build process

Build artifacts

Code signing

Windows code signing

macOS code signing

Publishing

Troubleshooting

Build fails on native modules

Out of memory errors

Missing build directory

Next steps