How to Build and Package Your NativePHP App for Windows, macOS, and Linux


NativePHP has opened the door for Laravel developers to build native desktop applications without abandoning the tools and patterns they already love. But after building your app, the next big step is packaging it for distribution — whether it’s for Windows, macOS, or Linux.

In this article, we’ll walk through the process of building and packaging your NativePHP app so it’s ready for users on all major desktop platforms.

🛠️ Prerequisites

Before you begin packaging, make sure you have the following:

  • A working NativePHP Laravel project

  • Installed Node.js, npm, and Electron

  • Access to build tools for Windows, macOS, and Linux

  • Installed Electron Forge or similar build framework

🧩 How NativePHP Bundles Work

NativePHP uses Electron under the hood to run your Laravel application inside a desktop shell. Electron allows you to:

  • Open browser-like windows

  • Package your app for cross-platform usage

  • Embed your Laravel backend within the Electron runtime

NativePHP handles the Laravel–Electron connection for you, but the build process involves configuring Electron’s packaging options.

🪄 Step-by-Step: Packaging with Electron Forge

1. Install Electron Forge

npm install --save-dev @electron-forge/cli
npx electron-forge import

This sets up your app to use Electron Forge, which automates much of the build and packaging process.

2. Update package.json Scripts

Add these scripts to your package.json:

"scripts": {
  "start": "electron-forge start",
  "make": "electron-forge make",
  "package": "electron-forge package"
}

This allows you to start, package, and build installers easily.

3. Set Entry Point in Electron

In your Electron main.js or main.ts file (configured by NativePHP), ensure it loads your Laravel server (via localhost or Unix socket) and opens the main window.

Example:

mainWindow.loadURL('http://127.0.0.1:8000');

NativePHP usually handles this, but it’s good to check.

4. Compile Assets and Start Laravel Server

Before building, run:

php artisan serve
npm run dev

Ensure your Laravel app is fully working before packaging.

🧳 Building for Each Platform

🪟 Windows:

Make sure you're on a Windows machine or using a Windows VM (cross-building is tricky on Windows).

npm run make

This creates an installer .exe file in the out directory.

🍎 macOS:

Run the same command on macOS:

npm run make

Electron Forge will generate a .dmg or .app bundle.

🐧 Linux:

Linux support includes .deb and .AppImage formats.

Make sure required dependencies like fakeroot, dpkg, and rpm are installed.

npm run make

🎯 Tips for Production

  • Use SQLite or file-based storage if your app needs local database access.

  • Optimize Laravel performance by running php artisan optimize.

  • Package Laravel inside the Electron app using php -S or use built-in server control from NativePHP.


With NativePHP and Electron, building cross-platform desktop apps using Laravel is no longer a dream. You can package your app just like any traditional desktop application and deliver it to users on Windows, macOS, or Linux.