Skip to main content
This guide covers how to build SlipStream GUI for distribution on different platforms.

​
Prerequisites

Before building, ensure you have:
  1. Completed the development setup
  2. Downloaded the SlipStream client binaries
  3. Installed all dependencies

​
Quick start

1

Install dependencies

Install all required npm packages (one-time setup):
npm install
This will download:
  • Electron
  • electron-builder
  • All required npm packages (socks-proxy-agent, socks, http-proxy, ip)
2

Download binaries

Download the SlipStream client binaries:
npm run download:binaries
3

Build the application

Build for your target platform(s):
npm run build:mac
4

Find the output

Built applications will be in the dist/ folder:
  • macOS: SlipStream-GUI-macOS-*.dmg
  • Windows: SlipStream-GUI-Windows-*.exe
  • Linux: SlipStream-GUI-Linux-*.AppImage, *.deb

​
Platform-specific builds

​
macOS

Build for both Apple Silicon and Intel:
npm run build:mac
Output: dist/SlipStream-GUI-macOS-ARM64.dmg and SlipStream-GUI-macOS-Intel.dmg
What gets bundled:
  • Electron runtime
  • Node.js dependencies
  • binaries/slipstream-client-mac-arm64
  • binaries/slipstream-client-mac-intel
  • Application assets and UI

​
Windows

Build both installer and portable versions:
npm run build:win
Output:
  • dist/SlipStream-GUI-Windows-x64.exe (installer)
  • dist/SlipStream-GUI-Windows-x64-Portable.exe
What gets bundled:
  • Electron runtime
  • Node.js dependencies
  • binaries/slipstream-client-win.exe
  • Application assets and UI

​
Linux

Build AppImage and DEB packages:
npm run build:linux
Output:
  • dist/SlipStream-GUI-Linux-x64.AppImage
  • dist/SlipStream-GUI-Linux-x64.deb
What gets bundled:
  • Electron runtime
  • Node.js dependencies
  • binaries/slipstream-client-linux
  • Application assets and UI

​
electron-builder configuration

The build configuration is defined in package.json under the build key: 
{
  "build": {
    "appId": "com.slipstream.gui",
    "productName": "SlipStream GUI",
    "directories": {
      "output": "dist"
    },
    "files": [
      "**/*",
      "!dist/**/*",
      "!*.md",
      "!settings.json"
    ],
    "mac": {
      "target": "dmg",
      "category": "public.app-category.utilities",
      "extraResources": [
        {
          "from": "binaries/slipstream-client-mac-arm64",
          "to": "binaries/slipstream-client-mac-arm64"
        },
        {
          "from": "binaries/slipstream-client-mac-intel",
          "to": "binaries/slipstream-client-mac-intel"
        }
      ]
    },
    "win": {
      "target": ["nsis", "portable"],
      "extraResources": [
        {
          "from": "binaries/slipstream-client-win.exe",
          "to": "binaries/slipstream-client-win.exe"
        }
      ]
    },
    "linux": {
      "target": ["AppImage", "deb"],
      "category": "Network",
      "extraResources": [
        {
          "from": "binaries/slipstream-client-linux",
          "to": "binaries/slipstream-client-linux"
        }
      ]
    }
  }
}

​
Key configuration options

  • extraResources: Bundles binaries into the app’s Resources folder
  • files: Specifies which files to include/exclude from the build
  • target: Defines output format (DMG, NSIS, AppImage, etc.)
  • category: App category for system integration

​
Binary bundling

The build process automatically verifies and bundles the required binaries:
  1. Verification step: Before building, the verify-binaries.js script runs automatically (defined as prebuild:* scripts in package.json)
  2. Checks performed:
    • Binary files exist in the binaries/ directory
    • Files are not Git LFS pointers
    • Files are larger than 10KB (real binaries, not placeholders)
  3. Bundling: electron-builder copies binaries to the app’s Resources folder
The build will fail if required binaries are missing. Always run npm run download:binaries before building.

​
Output directory

All built applications are placed in the dist/ folder: 
dist/
├── SlipStream-GUI-macOS-ARM64.dmg
├── SlipStream-GUI-macOS-Intel.dmg
├── SlipStream-GUI-Windows-x64.exe
├── SlipStream-GUI-Windows-x64-Portable.exe
├── SlipStream-GUI-Windows-x86.exe
├── SlipStream-GUI-Linux-x64.AppImage
└── SlipStream-GUI-Linux-x64.deb
The dist/ directory also contains temporary build artifacts that can be safely deleted.

​
What gets bundled

The built applications are completely self-contained:
  • ✅ Electron runtime
  • ✅ All Node.js dependencies
  • ✅ SlipStream client binaries (platform-specific)
  • ✅ Application UI and assets
  • ✅ No internet connection required to run
Users can install and use the app without any additional downloads or setup.

​
Distribution

The built DMG (macOS), EXE (Windows), and AppImage/DEB (Linux) installers can be distributed directly to users. They include everything needed to run the application.

​
User experience

After download:
  1. ✅ User downloads DMG/EXE/AppImage installer
  2. ✅ User installs (one click)
  3. ✅ User runs the app
  4. ✅ Everything works automatically - no manual actions needed!
What’s hidden from users:
  • ✅ SlipStream client binaries are bundled inside the app
  • ✅ Users never see these files
  • ✅ No terminal commands needed
  • ✅ No chmod or permission setup needed
  • ✅ App automatically handles all permissions

​
Troubleshooting

​
Build fails with permission errors

The app automatically sets execute permissions on first run. For development testing: 
chmod +x binaries/slipstream-client-mac-arm64
chmod +x binaries/slipstream-client-mac-intel

​
Missing dependencies

  1. Run npm install again
  2. Check that all dependencies in package.json are installed
  3. Clear npm cache: npm cache clean --force

​
App doesn’t find SlipStream client

  1. Make sure the binaries are present under binaries/:
    • binaries/slipstream-client-mac-arm64
    • binaries/slipstream-client-mac-intel
    • binaries/slipstream-client-win.exe
    • binaries/slipstream-client-linux
  2. Check the build logs to see if files were copied correctly
  3. The app automatically finds binaries in the Resources folder when packaged

​
Binaries are Git LFS pointers

If the verify script reports LFS pointers instead of real binaries: 
npm run download:binaries

​
Development mode testing

To test the app during development without building: 
npm start
This runs the app using the current source code with hot-reload capabilities.

​
Next steps

Contributing

Learn how to contribute to the project

Development overview

Understand the architecture and tech stack

Build docs developers (and LLMs) love

Get started for freeTalk to us