Build Native Desktop Apps with PHP Using NativePHP – A Step‑by‑Step Guide

Overview

NativePHP compiles PHP code into native binaries, allowing developers to create desktop applications that run directly on the OS without a web server or interpreter. The first stable desktop version (V1.0) was released on 2025‑04‑13.

Environment Requirements

PHP 8.3+

Laravel 11 or newer

Node 22+

Windows 10+, macOS 12+, or Linux

The optimal workflow is to run PHP and Node on the development machine.

Note: While you can develop in virtualized or container environments, you may encounter unexpected issues and need extra manual steps.

Example Project

Clone the repository

Official repository:

https://github.com/NativePHP/kitchen-sink

git clone [email protected]:NativePHP/kitchen-sink.git

Install backend dependencies

Run Composer to install required packages: composer install Successful installation shows a list of packages ending with DONE.

Install frontend dependencies

npm i

Start development mode

composer native:dev

When the command finishes, you should see output similar to the example, indicating that the Laravel app is running in a native desktop window.

Build for release

php artisan native:build

If the build succeeds, a dist folder containing an .exe file is created; double‑clicking it runs the desktop application.

Custom Installation

Install NativePHP via Composer: composer require nativephp/electron Or specify a PHP version explicitly:

/usr/local/php-8.3.20/bin/php /home/build/composer.phar require nativephp/electron

Then install dependencies and start the app:

php artisan native:install
php artisan native:serve

Common Errors

Q1: MissingAppKey

Run php artisan key:generate and ensure .env contains a valid APP_KEY like APP_KEY=base64:your_key.

Q2: Frontend startup failure

Make sure frontend dependencies are installed: npm i.

Q3: Service startup error about packageManager

Remove the "packageManager" field from package.json and reinstall with npm i.