Packaging (electron-builder)

Once your launcher is ready and tested, the final step is to package it into an executable file (.exe for Windows, .dmg for macOS, etc.) that your players can download and install.

We use electron-builder for this task. It is a powerful tool that handles compilation, compression, and code signing.

Prerequisites

Ensure you have the following assets ready in a build/ folder at the root of your project:

• icon.ico: The Windows icon (at least 256x256).
• icon.icns: The macOS icon (at least 512x512).
• icon.png: The Linux icon (512x512).

Configuration (electron-builder.yml)

Instead of cluttering your package.json, create a file named electron-builder.yml at the root of your project. This file controls how your launcher is built.

Here is a complete configuration with maximum customization options:

appId: com.yourserver.launcher
productName: "My Server Launcher"
copyright: "Copyright © 2026 My Server"

# The output folder where executables will be created
directories:
  output: dist
  buildResources: build

# Which files to include in the final app
files:
  - "dist/**/*"
  - "electron/**/*"
  - "dist-electron/**/*"
  - "package.json"
  - "!**/node_modules/*/{CHANGELOG.md,README.md,README,readme.md,readme}",
  - "!**/node_modules/*/{test,__tests__,tests,powered-test,example,examples}",
  - "!**/node_modules/*.d.ts",
  - "!**/node_modules/.bin",
  - "!**/*.{iml,o,hprof,orig,pyc,pyo,rbc,swp,csproj,sln,xproj}",
  - "!.editorconfig",
  - "!**/._*",
  - "!**/{.DS_Store,.git,.hg,.svn,CVS,RCS,SCCS,.gitignore,.gitattributes}",
  - "!**/{__pycache__,thumbs.db,.flowconfig,.idea,.vs,.nyc_output}",
  - "!**/{appveyor.yml,.travis.yml,circle.yml}",
  - "!**/{npm-debug.log,yarn.lock,.yarn-integrity,.yarn-metadata.json}"

publish:
  provider: generic
  url: "https://yourserver.com/launcher/updates/"

# WINDOWS CONFIGURATION
win:
  target: nsis
  icon: build/icon.ico
  legalTrademarks: "My Server"

# The Installer configuration (Setup.exe)
nsis:
  oneClick: false # Allow user to choose install path
  perMachine: false # Install for current user (no admin rights needed)
  allowToChangeInstallationDirectory: true
  shortcutName: "My Server"
  uninstallDisplayName: "My Server Launcher"
  createDesktopShortcut: true
  createStartMenuShortcut: true
  deleteAppDataOnUninstall: true
  artefactName: "${productName} Setup ${version}.${ext}"

# MACOS CONFIGURATION
mac:
  target: 
    - dmg
    - zip
  icon: build/icon.icns
  category: public.app-category.games
  darkModeSupport: true
  hardenedRuntime: true # Required for notarization
  gatekeeperAssess: false
  entitlements: build/entitlements.mac.plist
  entitlementsInherit: build/entitlements.mac.plist
  artefactName: "${productName} ${version}.${ext}"

# The DMG installer window appearance
dmg:
  background: build/dmg-background.png
  icon: build/dmg-icon.icns
  iconSize: 100
  title: "Install My Server"
  contents:
    - x: 130
      y: 220
    - x: 410
      y: 220
      type: link
      path: /Applications

# LINUX CONFIGURATION
linux:
  target: 
    - AppImage
    - deb
    - rpm
  icon: build/icon.png
  category: Game
  artefactName: "${productName}-${version}-linux.${ext}"

Building the project

To build your launcher, you must first compile your frontend (Vite) and then run electron-builder.

Add this script to your package.json:

"scripts": {
  "build": "tsc && vite build && electron-builder"
}

Then, simply run:

npm run build

Handling code signing

Code signing is crucial to prevent antivirus warnings (like Windows SmartScreen) and to allow the app to run on macOS.

Windows signing

If you have a code signing certificate (.pfx), you can sign your app automatically.

1. Place your certificate in a secure folder.
2. Update electron-builder.yml:

win:
  certificateFile: "certs/my-certificate.pfx"
  certificatePassword: "YOUR_PASSWORD" # Or use env variable CSC_KEY_PASSWORD

macOS signing & notarization

On macOS, signing is mandatory. If you don’t sign and “notarize” your app, it will not run on other people’s Macs.

1. You need an Apple Developer Account ($99/year).
2. Export your “Developer ID Application” certificate to your Keychain.
3. Add a notarize hook in your build process (see electron-builder docs for notarize.js).

Output files & EML AdminTool connection

Once the build finishes, check the dist/ folder.

Files to Upload (Per OS)

For the auto-update to work, you need to upload 3 files for each operating system you support.

Windows

File Type	Example Name	Description
Executable	MyLauncher Setup 1.0.0.exe	The main installer file.
Manifest	latest.yml	Contains version info and file hashes.
Blockmap	MyLauncher Setup 1.0.0.exe.blockmap	Used for differential updates (downloads only changed parts).

macOS (Apple Silicon & Intel)

File Type	Example Name	Description
Executable	MyLauncher-1.0.0-mac.zip	The application archive (preferred for updates).
Manifest	latest-mac.yml	Contains version info for macOS.
Blockmap	MyLauncher-1.0.0-mac.zip.blockmap	The blockmap associated with the ZIP.

Linux

File Type	Example Name	Description
Executable	MyLauncher-1.0.0.AppImage	The standalone executable.
Manifest	latest-linux.yml	Contains version info for Linux.
Blockmap	MyLauncher-1.0.0.AppImage.blockmap	The blockmap associated with the AppImage.

How to publish an update via EML AdminTool

When you have built a new version (e.g., moved from 1.0.0 to 1.0.1 in your package.json):

1. Run npm run build to generate the new files.
2. Go to EML AdminTool > Bootstraps.
3. Select the Bootstrap corresponding to your launcher (or create one).
4. Upload the files for the target OS:
   • Upload the new Executable (exe/zip/AppImage).
   • Upload the new Manifest (.yml).
   • Upload the new Blockmap (.exe.blockmap, etc.).
5. Save/Publish.

That’s it! Next time your users start the launcher, EML Lib will:

1. Download the .yml file from your AdminTool.
2. Compare the version with the local one.
3. If a new version is found, it uses the .blockmap to download only the modified bits of the code (making the update very fast).
4. Install the update and restart the launcher.

Troubleshooting

“Cannot create symbolic link” on Windows

If you get an error about symbolic links while building, enable Developer Mode in Windows Settings : Settings > System > Advanced > Developer Mode.

Antivirus false positives

Unsigned launchers are often flagged by generic antivirus heuristics.

• Solution: Submit your .exe to Microsoft for malware analysis (white-listing).
• Better Solution: Buy a Code Signing Certificate (EV or OV).