Linux AppDir & AppImage

Overview

While Hakobu produces standalone Linux executables that run directly, you may want to distribute them using standard Linux packaging formats. Hakobu supports two packaging modes for Linux: AppDir and AppImage.

AppDir

An AppDir is a self-contained directory structure that follows the AppDir specification. Use the --appdir flag to produce an AppDir instead of a single executable:

hakobu ./my-app --target node24-linux-x64 --output ./dist/MyApp.AppDir --appdir

This produces the following directory structure:

MyApp.AppDir/
├── AppRun              # Symlink to the executable
├── my-app.desktop      # Desktop entry file
├── my-app.png          # Application icon (if --icon is provided)
└── usr/
    └── bin/
        └── my-app      # The Hakobu executable

The AppRun entry point symlinks to usr/bin/my-app, so the AppDir can be executed directly:

./MyApp.AppDir/AppRun

If you provide an --icon flag with a PNG file, Hakobu places it at the root of the AppDir for desktop integration. The .desktop file is generated automatically from your package.json metadata.

AppImage

An AppImage bundles the AppDir into a single portable file that runs on most Linux distributions without installation. Use the --appimage flag:

hakobu ./my-app --target node24-linux-x64 --output ./dist/MyApp.AppImage --appimage

Hakobu creates the AppDir internally and then packages it into an AppImage using appimagetool. The result is a single executable file:

chmod +x ./dist/MyApp.AppImage
./dist/MyApp.AppImage

The --appimage flag requires appimagetool to be available on your system or CI runner. Install it from the AppImage releases page.

When to Use Each Format

Format	Use Case
Raw executable	Servers, CLI tools, Docker containers, embedded systems
AppDir	Development, custom packaging pipelines, Flatpak/Snap input
AppImage	Desktop app distribution, portable Linux apps

Combining with Multi-Target Builds

AppDir and AppImage flags apply only to Linux targets. When building for multiple platforms, Hakobu applies these flags to the Linux targets and ignores them for Windows and macOS:

hakobu ./my-app \
  --target node24-linux-x64,node24-win-x64,node24-macos-arm64 \
  --output ./dist/ \
  --appimage

This produces an AppImage for linux-x64, a standard .exe for win-x64, and a standard binary for macos-arm64.