Build System

Relevant source files

The following files were used as context for generating this wiki page:

• scripts/build-all.js
• scripts/debug-build.js
• scripts/build-nsis.js
• package.json
• scripts/deploy.js
• scripts/README.md
• ELECTRON-SETUP.md
• build-errors/error-1763198715230.json

The Skid-Inc build system is a collection of Node.js scripts and npm commands designed to automate the compilation, packaging, and deployment of the Electron application. It supports building for multiple platforms (Windows, macOS, Linux) from a single codebase, incorporating features like error handling, retry logic, detailed logging, and artifact management. The system is primarily driven by electron-builder and orchestrated by custom scripts located in the /scripts directory.

The core of the system is the build-all.js script, which provides a comprehensive, automated build process. This is complemented by scripts for deployment (deploy.js), debugging (debug-build.js), and specialized builds like the Windows NSIS installer (build-nsis.js). All build configurations and commands are centralized within package.json, making the process streamlined and easy to trigger.

Sources: scripts/README.md, package.json, scripts/build-all.js

Core Components

The build system is composed of several key scripts and configuration files.

Script/File	Description
package.json	Central configuration file. Defines npm scripts, dependencies (electron-builder), and the main build configuration object.
scripts/build-all.js	An automated, multi-platform build script with error handling, retry logic, logging, and build report generation.
scripts/deploy.js	Manages post-build tasks: collecting artifacts, generating checksums, creating release notes, and packaging files into a release archive.
scripts/build-nsis.js	A specialized script to build the Windows NSIS installer, which temporarily modifies package.json to enable the NSIS target.
scripts/debug-build.js	A diagnostic tool that analyzes the build environment, checks for required files, and provides system information to help debug failures.
build/prebuild.js	A script that runs before the main build process, performing validation and creating build information.

Sources: package.json, scripts/README.md, scripts/build-all.js, scripts/deploy.js, scripts/build-nsis.js, scripts/debug-build.js, build-errors/error-1763198715230.json

Build & Release Flow

The full release process, from building the application to preparing deployment artifacts, can be triggered with a single command. The following diagram illustrates the high-level flow when running npm run release.

This diagram shows the sequence initiated by npm run release, which first executes the automated build script and then the deployment script.

Sources: package.json:28, scripts/build-all.js, scripts/deploy.js

NPM Scripts

The package.json file defines a set of scripts to manage the build lifecycle.

Command	Description
build	Runs prebuild and then builds for the current platform using electron-builder.
build:win	Builds for Windows.
build:mac	Builds for macOS.
build:linux	Builds for Linux.
build:all	Builds for Windows, macOS, and Linux.
build:automated	Executes the build-all.js script for a robust, multi-platform build.
build:nsis	Executes scripts/build-nsis.js to create a Windows NSIS installer.
build:debug	Runs the scripts/debug-build.js diagnostic tool.
deploy	Executes scripts/deploy.js to package artifacts for a release.
release	A convenience script that runs build:release and deploy:github sequentially.

Sources: package.json:16-30, ELECTRON-SETUP.md:16-21, scripts/README.md:21-25

Build Configuration

The primary build configuration is located in the build section of package.json. This object configures electron-builder.

Main Configuration

"build": {
  "appId": "com.totominc.skidinc",
  "productName": "Skid-Inc",
  "copyright": "Copyright © 2025 TotomInc",
  "compression": "store",
  "directories": {
    "output": "dist",
    "buildResources": "build"
  },
  "files": [
    "src/**/*",
    "app/**/*",
    "index.html",
    "icons/**/*",
    "!**/*.md",
    "favicon.png"
  ],
  "publish": {
    "provider": "github",
    "owner": "TotomInc",
    "repo": "skid-inc"
  }
}

Sources: package.json:33-66

Platform-Specific Targets

The configuration specifies different build targets for each operating system.

Platform	Targets	Architectures
Windows	portable	x64
macOS	dmg, zip	x64, arm64
Linux	AppImage, deb, rpm	x64

Note: The build:win-nsis script temporarily adds an nsis target for Windows builds.

Sources: package.json:79-91, 93-109, 123-140, scripts/build-nsis.js:46-55

Automated Build (build-all.js)

This script provides a resilient, automated build process managed by the BuildManager class.

Features

• Environment Validation: Checks for Node.js, electron-builder, and required source files before starting.
• Directory Cleaning: Removes the previous build's output directory (dist).
• Platform-Specific Builds: Iterates through configured platforms (win, mac, linux) and executes the corresponding npm run build:<platform> command.
• Retry Logic: If a platform build fails, it is automatically retried up to maxRetries (default: 3) times.
• Timeout: Each platform build has a timeout (default: 5 minutes) to prevent hangs.
• Logging: All actions are logged to both the console and a build.log file.
• Reporting: Generates a build-report.json file in the output directory with build results, durations, and a list of generated artifacts.

Sources: scripts/build-all.js:12-19, 70-73, 100-103, 153-156, 196-200

Class Structure

The script uses two main classes to organize its logic.

This diagram shows the BuildManager class, which orchestrates the build process, and its composition of the Logger class for handling output.

Sources: scripts/build-all.js:22-48, 51-260

Deployment (deploy.js)

After a successful build, scripts/deploy.js is used to prepare the artifacts for distribution. It is managed by the DeployManager class.

The deployment process follows these steps:

1. Load package.json: To get the current version.
2. Create Release Directory: Creates a versioned subdirectory inside releases (e.g., releases/v0.0.2).
3. Copy Artifacts: Copies distributable files (.exe, .dmg, .AppImage, etc.) from the dist directory to the new release directory.
4. Calculate Checksums: Generates a checksums.txt file containing SHA256 hashes for all artifacts.
5. Generate Documentation: Creates a RELEASE_NOTES.md file and a manifest.json file with metadata about the release.
6. Create Archive: Packages all contents of the release directory into a single .zip file.

Sources: scripts/deploy.js:15-29, 66-99, 150-159, 191-220, 222-243

Debugging and Error Handling

Debug Script (debug-build.js)

The scripts/debug-build.js script is a powerful diagnostic tool for troubleshooting build failures. When executed, it prints a comprehensive report to the console, including:

• System Information (OS, Arch, Node.js version, Memory)
• Project Information (Name, Version)
• A checklist of required files and their status
• Status of build dependencies
• Contents of the dist directory
• Key environment variables
• A summary of the electron-builder configuration
• Memory analysis and recommendations
• Suggested build commands to try

Sources: scripts/debug-build.js, scripts/README.md:155-161

Error Logging

Build failures are captured and logged. The build-all.js script logs errors to build.log. The older automated-build.js (referenced in error logs) saved detailed JSON reports of failures into the build-errors/ directory. These reports contain a timestamp, stack trace, and a full build log leading up to the failure, which is invaluable for diagnostics.

An example error from the logs shows a Cannot find module error during the electron-builder process, indicating a misconfiguration in the beforeBuild hook.

Sources: build-errors/error-1763198715230.json, build-errors/error-1763198776676.json, scripts/build-all.js:30-36, 140-151