Skip to main content

Build & Release

How to build FitFileViewer for distribution.

Development Build​

Quick Build​

# Build for current platform
npm run build

Development Package​

# Create unpacked build (faster, for testing)
npm run package

Production Build​

Single Platform​

# Windows
npm run build -- --win

# macOS
npm run build -- --mac

# Linux
npm run build -- --linux

All Platforms​

# Build for all platforms
npm run build:all

Build Configuration​

Root Builder Config​

Packaging is configured from the repository root:

  • electron-builder.config.cjs owns Electron Builder targets, artifact names, publish settings, and platform options.
  • The root package.json is the app manifest for version, runtime dependencies, exports, and publish metadata.
  • Packaged file inclusion is limited to root package metadata and dist/ runtime output.
// electron-builder.config.cjs
const rootPackageFiles = ["dist/**", "package.json"];

module.exports = {
 appId: appPackage.appid,
 productName: appPackage.productName,
 files: rootPackageFiles,
 artifactName: "Fit-File-Viewer-${platform}-${arch}-${version}.${ext}",
 publish: [{ provider: "github", owner: "Nick2bad4u", repo: "FitFileViewer" }],
};

Output Formats​

Windows​

FormatDescription
NSISStandard installer
MSIWindows Installer
PortableNo installation
SquirrelAuto-updating

macOS​

FormatDescription
DMGDisk image
PKGInstaller package
ZIPArchive

Linux​

FormatDescription
AppImageUniversal format
DEBDebian/Ubuntu
RPMFedora/RHEL
SnapSnap package

CI/CD Pipeline​

Builds are automated via GitHub Actions:

# .github/workflows/Build.yml
name: Build
on:
 push:
  branches: [main]
 release:
  types: [published]

jobs:
 build:
  runs-on: ${{ matrix.os }}
  strategy:
   matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]
  steps:
   - uses: actions/checkout@v4
   - uses: actions/setup-node@v4
   - run: npm ci
   - run: npm run build

Release Process​

1. Update Version​

# Update the Electron app version
npm run release:bump-version

2. Update Changelog​

npm run changelog

3. Create Release​

# Push tag
git push --tags

# GitHub Actions builds and publishes

4. Verify Release​

Check GitHub Releases for:

  • All platform builds
  • Checksums
  • Release notes

Code Signing​

Run npm run release:check-signing before signed packaging when REQUIRE_CODE_SIGNING=true. The command reports missing variables before electron-builder starts.

Local and rehearsal builds are unsigned by default:

npm run package
npm run package:unsigned

Production releases follow the same unsigned-by-default policy. The Build And Release Electron App workflow exposes a require-code-signing input; leave it disabled for the established release path and enable it only after the Windows and macOS signing credentials have been configured.

For a failed run that already created an unpublished version tag, use reuse-current-version=true only after moving that tag to the exact retry commit. The workflow validates the package version, tag, and checked-out commit match before rebuilding, preventing an accidental extra version bump.

Both commands force FFV_FORCE_UNSIGNED_PACKAGE=true, CSC_IDENTITY_AUTO_DISCOVERY=false, and REQUIRE_CODE_SIGNING=false before electron-builder starts. Use them for local package validation and release rehearsals where credentials should not affect the result.

Use the signed path only when the platform signing secrets are available:

npm run package:signed

That command runs npm run release:check-signing:required first, then starts electron-builder with REQUIRE_CODE_SIGNING=true.

Windows​

Signed Windows builds require:

  • WIN_CSC_LINK or CSC_LINK
  • CSC_KEY_PASSWORD

macOS​

Signed macOS builds require:

  • CSC_LINK
  • CSC_KEY_PASSWORD
  • CSC_INSTALLER_LINK
  • CSC_INSTALLER_KEY_PASSWORD

Notarization also requires one of these credential sets:

  • APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, and APPLE_TEAM_ID
  • APPLE_API_KEY, APPLE_API_KEY_ID, and APPLE_API_ISSUER
  • APPLE_KEYCHAIN_PROFILE

For GitHub Actions, store the base64-encoded .p8 key as APPLE_API_KEY_BASE64, plus APPLE_API_KEY_ID and APPLE_API_ISSUER. The workflow writes the decoded key to RUNNER_TEMP and exports its path as APPLE_API_KEY; do not store raw key contents in APPLE_API_KEY, because electron-builder interprets that variable as a filesystem path.

Linux release builds do not require signing variables. Windows 7 compatibility is limited to carried-forward legacy release assets from build-win7.yml; the current app is not rebuilt for Windows 7.

After signed Windows or macOS packaging, run:

npm run release:verify-signing-artifacts

For the full signed release verification path, run:

npm run verify:release:signed

That command runs fast checks, the docs build, audit, Playwright smoke, signed packaging, signature artifact verification, and packaged smoke in order.

The verifier checks Windows .exe and .msi files with Get-AuthenticodeSignature, checks macOS .app bundles with codesign, and writes release-dist/signing-verification-report.json. The primary release workflow uploads that report with the platform artifacts.

Troubleshooting Builds​

Common Issues​

Build fails on Windows:

# Clear cache
npm cache clean --force
rm -rf node_modules
npm install

macOS signing fails:

  • Verify certificate in Keychain
  • Check code signing identity

Linux missing dependencies:

# Install build tools
sudo apt-get install build-essential

Related: Development Setup