Packaging

veloxkit package produces a platform-specific distributable from your app.

Quick start

# Package for the current platform
npx veloxkit-cli package
 
# Output is in dist/
# macOS:   dist/My App.dmg
# Windows: dist/My App Setup.exe
# Linux:   dist/my-app.AppImage

Build first, then package

package runs build automatically, but you can separate them:

npx veloxkit-cli build     # produces dist/bundle/
npx veloxkit-cli package   # wraps dist/bundle/ into an installer

Cross-compilation

Package for a different platform from your current OS:

npx veloxkit-cli package --target windows
npx veloxkit-cli package --target macos
npx veloxkit-cli package --target linux

⚠️

Cross-compilation requires Docker on non-macOS hosts for the macOS target (due to code signing requirements). Windows and Linux cross-compile without Docker.

Output formats

macOS

Format	Flag	Notes
`.dmg`	`--format dmg`	Default. Drag-to-Applications installer.
`.app`	`--format app`	Bare app bundle.
`.pkg`	`--format pkg`	macOS package installer.

Windows

Format	Flag	Notes
NSIS installer (`.exe`)	`--format nsis`	Default. Start menu + uninstaller.
MSI	`--format msi`	Enterprise-friendly.
Portable (`.exe`)	`--format portable`	No installer, single executable.

Linux

Format	Flag	Notes
AppImage	`--format appimage`	Default. Runs on any distro.
`.deb`	`--format deb`	Debian/Ubuntu.
`.rpm`	`--format rpm`	Fedora/RHEL.

Code signing

macOS

# Requires Apple Developer account and Xcode Command Line Tools
npx veloxkit-cli package --sign --identity "Developer ID Application: Your Name (TEAMID)"
 
# Notarize after signing (required for distribution outside App Store)
npx veloxkit-cli notarize \
  --apple-id you@example.com \
  --team-id YOURTEAMID \
  --password "@keychain:AC_PASSWORD"

Windows

npx veloxkit-cli package --sign --cert path/to/cert.pfx --cert-password yourpassword

App icon

VeloxKit generates all required icon sizes from a single source image. Place a 1024×1024 PNG at:

assets/icon.png

VeloxKit generates:

icon.icns (macOS — all sizes 16px–1024px)
icon.ico (Windows — 16px, 32px, 48px, 256px)
AppImage icon (Linux — 512px)

Configure package output

In veloxkit.config.ts:

export default defineConfig({
  name: 'my-notes',
  productName: 'My Notes',
  version: '1.0.0',
  identifier: 'com.yourname.my-notes',
 
  package: {
    outDir: 'dist',
    targets: ['dmg', 'nsis', 'appimage'],  // build all three in CI
 
    macos: {
      category: 'public.app-category.productivity',
      minimumSystemVersion: '12.0',
      entitlements: './entitlements.plist',  // if you need special entitlements
    },
 
    windows: {
      installerIcon: './assets/installer-icon.ico',
      license: './LICENSE.rtf',
    },
 
    linux: {
      category: 'Utility',
      mimeType: ['text/plain'],
    },
  },
})

CI/CD example (GitHub Actions)

name: Release
 
on:
  push:
    tags: ['v*']
 
jobs:
  package:
    strategy:
      matrix:
        os: [macos-14, windows-latest, ubuntu-22.04]
    runs-on: ${{ matrix.os }}
 
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npx veloxkit-cli package
        env:
          SIGN_CERT: ${{ secrets.SIGN_CERT }}
          SIGN_PASSWORD: ${{ secrets.SIGN_PASSWORD }}
      - uses: actions/upload-artifact@v4
        with:
          name: dist-${{ matrix.os }}
          path: dist/

Canvas 3D Auto-Updater