Skip to main content

​
Introduction

NativePHP provides a comprehensive build system that transforms your Laravel application into production-ready native desktop applications. The build process handles everything from copying your application files to bundling PHP binaries and creating platform-specific installers.

​
How Building Works

The build process involves several key steps:
1

Prepare Build Directory

NativePHP creates a clean build directory and copies your application files, excluding development dependencies and sensitive files.
2

Environment Cleanup

Sensitive environment variables and development keys are removed from your .env file for production distribution.
3

Optimize Dependencies

Composer dependencies are optimized with --no-dev flag, removing development packages to reduce bundle size.
4

Bundle PHP Runtime

Platform-specific PHP binaries are downloaded and bundled with your application.
5

Create Executable

Electron Builder packages everything into native executables and installers for your target platforms.

​
Build Targets

NativePHP supports building for multiple platforms and architectures:

​
Windows

  • x64 - 64-bit Windows applications
  • Installer formats - NSIS installer with desktop shortcuts

​
macOS

  • x64 - Intel-based Macs
  • arm64 - Apple Silicon (M1/M2/M3)
  • Installer formats - DMG disk images and .app bundles

​
Linux

  • x64 - 64-bit Linux distributions
  • arm64 - ARM-based Linux systems
  • Installer formats - AppImage and .deb packages

​
Build Commands

NativePHP uses npm scripts defined in the Electron resources to handle building: 
# Build for all platforms
npm run build:all

# Build for specific platforms
npm run build:mac
npm run build:win
npm run build:linux

# Build for specific architectures
npm run build:mac-arm64
npm run build:mac-x64
npm run build:win-x64
npm run build:linux-x64
npm run build:linux-arm64
All build commands use the -p never flag to prevent automatic publishing. Use publish:* commands when ready to distribute.

​
Build Output

Built applications are output to the nativephp/electron/dist directory in your Laravel application: 
your-app/
├── nativephp/
│   └── electron/
│       └── dist/
│           ├── YourApp-1.0.0-setup.exe      # Windows installer
│           ├── YourApp-1.0.0-arm64.dmg      # macOS ARM installer
│           ├── YourApp-1.0.0-x64.dmg        # macOS Intel installer
│           ├── YourApp-1.0.0.AppImage       # Linux AppImage
│           └── YourApp-1.0.0.deb            # Linux Debian package

​
Build Directory Structure

During the build process, NativePHP creates a temporary build directory: 
build/
├── app/                    # Your Laravel application
│   ├── app/
│   ├── bootstrap/
│   ├── config/
│   ├── public/
│   ├── resources/
│   ├── routes/
│   ├── storage/
│   ├── vendor/            # Production dependencies only
│   └── .env               # Cleaned environment file
└── php/                   # Platform-specific PHP binaries
The build directory is automatically cleaned before each build to ensure a fresh start.

​
Pre and Post Build Scripts

You can define custom scripts to run before and after the build process in your config/nativephp.php: 
return [
    'prebuild' => [
        'npm run build',              // Build frontend assets
        'php artisan optimize',       // Optimize Laravel
    ],
    
    'postbuild' => [
        'rm -rf public/build',        // Clean up temporary files
    ],
];
Pre and post build scripts run with a 300-second timeout. Ensure your scripts complete within this timeframe.

​
File Exclusions

NativePHP automatically excludes certain files and directories from your build to reduce bundle size and improve security. See the Configuration page for details on customizing exclusions.

​
Next Steps

Build Configuration

Configure build settings, file exclusions, and platform-specific options

Bundling Process

Understand how NativePHP bundles your application and dependencies

Code Signing

Sign your applications for macOS and Windows distribution

Auto-Updates

Configure automatic updates for your distributed applications

Build docs developers (and LLMs) love

Get started for freeTalk to us