This document explains how to build installer packages for Yemaya Desktop on Windows, macOS, and Linux.
Prerequisites#
All Platforms#
- Node.js 20.x or later
- pnpm 10.x or later
- Git
Windows#
- Windows 10/11
- Visual Studio Build Tools (for native modules)
- Windows SDK (for code signing)
macOS#
- macOS 13+ (Ventura or later)
- Xcode Command Line Tools
- Apple Developer certificate (for signing/notarization)
Linux#
- Ubuntu 20.04+ or equivalent
rpm,fakeroot,dpkgpackages for building installers
Quick Start#
# Clone the repository
git clone https://github.com/yemaya/yemaya.git
cd yemaya
# Install dependencies
pnpm install
# Build the desktop app
cd apps/yemaya/studio-desktop
pnpm build
# Create installer for current platform
pnpm make
Generating Icons#
Before building, generate platform-specific icons from the source SVG:
# Install icon generation dependencies
npm install sharp png-to-ico
# Generate icons
pnpm generate-icons
Required Icon Files#
| File | Platform | Size | Description |
|---|---|---|---|
| icon.png | All | 512x512 | Primary application icon |
| icon.ico | Windows | Multi | Windows icon (16-256px) |
| icon.icns | macOS | Multi | macOS icon bundle |
| dmg-background.png | macOS | 540x380 | DMG installer background |
| installing.gif | Windows | - | Squirrel installer animation |
macOS Icon Generation#
On macOS, use iconutil to create .icns:
# Create iconset directory
mkdir icon.iconset
# Copy PNG files with correct names
cp icon-16.png icon.iconset/icon_16x16.png
cp icon-32.png icon.iconset/icon_16x16@2x.png
cp icon-32.png icon.iconset/icon_32x32.png
cp icon-64.png icon.iconset/icon_32x32@2x.png
cp icon-128.png icon.iconset/icon_128x128.png
cp icon-256.png icon.iconset/icon_128x128@2x.png
cp icon-256.png icon.iconset/icon_256x256.png
cp icon-512.png icon.iconset/icon_256x256@2x.png
cp icon-512.png icon.iconset/icon_512x512.png
cp icon-1024.png icon.iconset/icon_512x512@2x.png
# Generate icns
iconutil -c icns icon.iconset -o icon.icns
Build Commands#
Development Build#
# Build for development (no packaging)
pnpm build
# Start the app in development mode
pnpm dev
Package Without Installer#
# Package the app (creates executable but no installer)
pnpm package
Create Installers#
# Build installer for current platform
pnpm make
# Build for specific platform
pnpm make --platform darwin # macOS
pnpm make --platform win32 # Windows
pnpm make --platform linux # Linux
# Build for specific architecture
pnpm make --arch x64 # Intel/AMD 64-bit
pnpm make --arch arm64 # Apple Silicon / ARM64
Publish to GitHub Releases#
# Publish to GitHub (requires GITHUB_TOKEN)
pnpm publish
Code Signing#
macOS#
Set these environment variables for code signing and notarization:
export APPLE_ID="your@email.com"
export APPLE_PASSWORD="xxxx-xxxx-xxxx-xxxx"
export APPLE_TEAM_ID="ABCD1234EF"
Verify your signing configuration:
pnpm check-signing
See CODE_SIGNING.md for detailed setup instructions.
Windows#
Set these environment variables for Windows signing:
export WINDOWS_CERTIFICATE_FILE="/path/to/certificate.pfx"
export WINDOWS_CERTIFICATE_PASSWORD="your-password"
CI/CD Build#
The desktop build workflow (.github/workflows/desktop-build.yml)
automatically:
- Runs on pushes to
mainthat affect desktop code - Tests the application
- Builds installers for all platforms in parallel
- Uploads build artifacts
- Optionally publishes to GitHub Releases
Required Secrets#
Configure these secrets in your GitHub repository:
| Secret | Description |
|---|---|
APPLE_ID |
Apple ID email for notarization |
APPLE_PASSWORD |
App-specific password for Apple |
APPLE_TEAM_ID |
Apple Developer Team ID |
WINDOWS_CERTIFICATE_FILE |
Base64-encoded .pfx certificate |
WINDOWS_CERTIFICATE_PASSWORD |
Certificate password |
GITHUB_TOKEN |
Auto-provided by GitHub Actions |
Manual Release#
Trigger a release build manually:
- Go to Actions > Desktop Build
- Click "Run workflow"
- Enable "Publish release to GitHub"
- Click "Run workflow"
Build Output#
After building, find installers in:
apps/yemaya/studio-desktop/out/make/
├── squirrel.windows/
│ └── x64/
│ ├── Yemaya-{version} Setup.exe
│ └── yemaya-{version}-full.nupkg
├── dmg/
│ └── Yemaya-{version}-{arch}.dmg
├── zip/
│ └── darwin/
│ └── Yemaya-darwin-{arch}-{version}.zip
├── deb/
│ └── x64/
│ └── yemaya_{version}_amd64.deb
└── rpm/
└── x64/
└── yemaya-{version}.x86_64.rpm
Troubleshooting#
Build Fails on Windows#
Native module compilation errors:
- Install Visual Studio Build Tools
- Run from "x64 Native Tools Command Prompt"
Signing errors:
- Verify certificate file path is correct
- Check certificate password
- Ensure certificate hasn't expired
Build Fails on macOS#
Signing identity not found:
security find-identity -v -p codesigning
Ensure your Developer ID Application certificate is installed.
Notarization fails:
- Verify App-Specific Password is correct
- Check Apple Developer account status
- Review notarization log for specific issues
"App is damaged" error:
xattr -cr /Applications/Yemaya.app
Build Fails on Linux#
Missing dependencies:
sudo apt-get update
sudo apt-get install -y rpm fakeroot dpkg
Permission errors:
chmod +x node_modules/.bin/*
Performance Tips#
- Use caching - CI caches node_modules to speed up builds
- Build in parallel - Each platform builds on its own runner
- Skip tests for releases - Use
--skip-testsflag for production builds - Use ARM runners - Apple Silicon builds are faster on native runners