Skip to main content

​
Quick Start

Build your first native desktop application with NativePHP in just a few minutes. This guide will walk you through creating a simple “Hello World” desktop app.

​
Prerequisites

Before starting, make sure you’ve completed:
1

Installation

Install NativePHP Desktop in your Laravel project
2

Configuration

Publish the configuration files with php artisan vendor:publish

​
Step 1: Bootstrap Your Application

Open app/Providers/NativeAppServiceProvider.php (created during installation). This is where you configure your desktop application’s behavior.

​
Create Your First Window

In the boot() method, use the Window facade to create and configure your main application window:
app/Providers/NativeAppServiceProvider.php
<?php

namespace App\Providers;

use Native\Desktop\Facades\Window;
use Native\Desktop\Facades\Menu;
use Native\Desktop\Menu\Menu as MenuBuilder;
use Native\Desktop\Menu\Items\MenuItem;

class NativeAppServiceProvider
{
    public function boot(): void
    {
        Window::open()
            ->title('My First Desktop App')
            ->width(800)
            ->height(600)
            ->rememberState(); // Remember window size and position
    }
}
The rememberState() method automatically saves and restores the window’s size and position between sessions.

​
Step 2: Create a Welcome View

Create a simple welcome page for your desktop app. Update your resources/views/welcome.blade.php:
resources/views/welcome.blade.php
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ config('app.name') }}</title>
    <style>
        body {
            margin: 0;
            padding: 0;
            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
            display: flex;
            justify-content: center;
            align-items: center;
            height: 100vh;
            color: white;
        }
        .container {
            text-align: center;
        }
        h1 {
            font-size: 3rem;
            margin-bottom: 1rem;
        }
        p {
            font-size: 1.2rem;
            opacity: 0.9;
        }
        .button {
            margin-top: 2rem;
            padding: 12px 24px;
            background: white;
            color: #667eea;
            border: none;
            border-radius: 8px;
            font-size: 1rem;
            cursor: pointer;
            font-weight: 600;
        }
        .button:hover {
            transform: scale(1.05);
        }
    </style>
</head>
<body>
    <div class="container">
        <h1>Welcome to NativePHP!</h1>
        <p>Your desktop application is ready.</p>
        <button class="button" onclick="alert('Hello from your desktop app!')">
            Click Me
        </button>
    </div>
</body>
</html>

​
Step 3: Run Your Desktop App

Start your Laravel development server: 
php artisan serve
Then visit http://localhost:8000 in your browser. In development mode, your application runs in the browser for easy testing.
During development (APP_DEBUG=true), your app runs in a regular browser. When you build for production, it will run as a native desktop application.

​
Step 4: Add Native Features

Let’s add some native desktop features to make your app more powerful.

​
Application Menu

Add a custom menu to your application:
app/Providers/NativeAppServiceProvider.php
<?php

namespace App\Providers;

use Native\Desktop\Facades\Window;
use Native\Desktop\Facades\Menu;
use Native\Desktop\Menu\Menu as MenuBuilder;
use Native\Desktop\Menu\Items\MenuItem;

class NativeAppServiceProvider
{
    public function boot(): void
    {
        Window::open()
            ->title('My First Desktop App')
            ->width(800)
            ->height(600)
            ->rememberState();
            
        Menu::create(
            MenuBuilder::new()
                ->label('File')
                ->items([
                    MenuItem::new('About', 'about'),
                    MenuItem::separator(),
                    MenuItem::new('Quit', 'quit'),
                ]),
            MenuBuilder::new()
                ->label('Edit')
                ->items([
                    MenuItem::role('undo'),
                    MenuItem::role('redo'),
                    MenuItem::separator(),
                    MenuItem::role('cut'),
                    MenuItem::role('copy'),
                    MenuItem::role('paste'),
                ])
        );
    }
}

​
Native Notifications

Add native system notifications:
app/Http/Controllers/NotificationController.php
<?php

namespace App\Http\Controllers;

use Native\Desktop\Facades\Notification;

class NotificationController extends Controller
{
    public function send()
    {
        Notification::new()
            ->title('Hello from NativePHP!')
            ->message('Your notification was sent successfully.')
            ->show();
            
        return response()->json(['status' => 'sent']);
    }
}

​
Multiple Windows

Open additional windows:
app/Providers/NativeAppServiceProvider.php
public function boot(): void
{
    // Main window
    Window::open('main')
        ->title('My First Desktop App')
        ->width(800)
        ->height(600)
        ->rememberState();
}
Then open a secondary window from your code: 
use Native\Desktop\Facades\Window;

// Open a settings window
Window::open('settings')
    ->title('Settings')
    ->url(route('settings'))
    ->width(600)
    ->height(400)
    ->resizable(false);

​
Step 5: Advanced Window Configuration

Customize your window appearance and behavior: 
Window::open()
    ->title('Frameless App')
    ->width(800)
    ->height(600)
    ->frameless()
    ->transparent();

​
Step 6: Working with Local Storage

NativePHP provides access to native file system directories: 
use Illuminate\Support\Facades\Storage;

// Access user's documents folder
$documents = Storage::disk('documents');
$documents->put('notes.txt', 'My notes');

// Access user's downloads folder
$downloads = Storage::disk('downloads');
$files = $downloads->files();

// Access app data folder
$appData = Storage::disk('app_data');
$appData->put('config.json', json_encode($config));

documents

User’s Documents folder

downloads

User’s Downloads folder

app_data

Application data storage

desktop

User’s Desktop

pictures

User’s Pictures folder

videos

User’s Videos folder

​
Step 7: Database Usage

NativePHP automatically configures a SQLite database for your application: 
use Illuminate\Support\Facades\DB;

// Create a migration
php artisan make:migration create_notes_table

// Run migrations
php artisan native:migrate

// Use Eloquent as normal
use App\Models\Note;

$note = Note::create([
    'title' => 'My First Note',
    'content' => 'Hello from NativePHP!',
]);
The database is automatically created at database/nativephp.sqlite in development mode. In production, it’s stored in the user’s application data directory.

​
Step 8: Background Tasks with Queues

Run background jobs using Laravel queues:
app/Jobs/ProcessData.php
<?php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Native\Desktop\Facades\Notification;

class ProcessData implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable;

    public function handle(): void
    {
        // Do some work
        sleep(2);
        
        // Notify when done
        Notification::new()
            ->title('Task Complete')
            ->message('Your data has been processed.')
            ->show();
    }
}
Dispatch the job: 
use App\Jobs\ProcessData;

ProcessData::dispatch();
Queue workers are automatically started based on your config/nativephp.php configuration:
config/nativephp.php
'queue_workers' => [
    'default' => [
        'queues' => ['default'],
        'memory_limit' => 128,
        'timeout' => 60,
        'sleep' => 3,
    ],
],

​
Complete Example

Here’s a complete example combining multiple features:
app/Providers/NativeAppServiceProvider.php
<?php

namespace App\Providers;

use Native\Desktop\Facades\Window;
use Native\Desktop\Facades\Menu;
use Native\Desktop\Facades\GlobalShortcut;
use Native\Desktop\Facades\Notification;
use Native\Desktop\Menu\Menu as MenuBuilder;
use Native\Desktop\Menu\Items\MenuItem;

class NativeAppServiceProvider
{
    public function boot(): void
    {
        // Configure main window
        Window::open()
            ->title(config('app.name'))
            ->width(1024)
            ->height(768)
            ->minWidth(800)
            ->minHeight(600)
            ->rememberState();
        
        // Create application menu
        Menu::create(
            MenuBuilder::new()
                ->label('File')
                ->items([
                    MenuItem::new('New Note', 'note.new')
                        ->accelerator('CmdOrCtrl+N'),
                    MenuItem::separator(),
                    MenuItem::new('Quit', 'quit')
                        ->accelerator('CmdOrCtrl+Q'),
                ]),
            MenuBuilder::new()
                ->label('Edit')
                ->items([
                    MenuItem::role('undo'),
                    MenuItem::role('redo'),
                    MenuItem::separator(),
                    MenuItem::role('cut'),
                    MenuItem::role('copy'),
                    MenuItem::role('paste'),
                ]),
            MenuBuilder::new()
                ->label('View')
                ->items([
                    MenuItem::role('togglefullscreen'),
                    MenuItem::role('toggledevtools'),
                ])
        );
        
        // Register global shortcuts
        GlobalShortcut::register('CmdOrCtrl+Shift+N', function () {
            Notification::new()
                ->title('Shortcut Pressed')
                ->message('You pressed Cmd/Ctrl+Shift+N')
                ->show();
        });
    }
}

​
Next Steps

Now that you have a working desktop application, explore more features:

Windows

Learn advanced window management techniques

Menus

Create custom application and context menus

Notifications

Show native system notifications

System Integration

Access clipboard, file dialogs, and system info

Auto Updates

Implement automatic application updates

Building

Build and distribute your application

​
Development Tips

Running in Development: Your app runs in a browser during development. To test as a true desktop app, you’ll need to build it for your platform.
Hot Reloading: Use Laravel’s built-in development server with hot reloading for the best development experience. Changes to your Blade views and assets will be reflected immediately.

​
Common Patterns

Open links in the user’s default browser: 
use Native\Desktop\Facades\Shell;

Shell::openExternal('https://nativephp.com');

​
Show File Dialogs

use Native\Desktop\Facades\Window;

// This feature requires additional implementation
// Check the Windows documentation for dialog APIs

​
Access System Information

use Native\Desktop\Facades\System;

$platform = System::platform(); // 'darwin', 'win32', 'linux'
$version = System::version();
$arch = System::arch();

​
Troubleshooting

​
Window Not Opening

Ensure your NativeAppServiceProvider is correctly referenced in config/nativephp.php:
config/nativephp.php
'provider' => \App\Providers\NativeAppServiceProvider::class,

​
Database Errors

Create and migrate the database manually: 
php artisan native:migrate

​
Assets Not Loading

Ensure your assets use absolute URLs or the asset() helper: 
<link href="{{ asset('css/app.css') }}" rel="stylesheet">
Congratulations! You’ve built your first NativePHP Desktop application. Continue exploring the documentation to unlock more powerful native features.

Build docs developers (and LLMs) love

Get started for freeTalk to us