Upgrade Guide

Upgrading To 4.0 From 3.x#

v4's headline is SuperNative — fully native UI. Most of the release is additive, but there is one breaking change to your dependencies: a handful of APIs that used to be separate plugins are now core built-ins.

Device, Dialog, File and System are now built in#

Device, Dialog, File, and System now ship inside nativephp/mobile — their native bridge functions are registered by core. nativephp/mobile v4 declares a Composer conflict with the four standalone plugins, so composer update will refuse to resolve until you remove them.

The quickest way is the --core-v4 flag, which finds whichever of the four you have installed, unregisters each from your NativeServiceProvider, and removes them all in a single composer remove:

php artisan native:plugin:uninstall --core-v4

Add --force to skip the confirmation prompt — handy when sweeping across several apps:

php artisan native:plugin:uninstall --core-v4 --force

Or uninstall them one at a time (this also unregisters each from your NativeServiceProvider):

php artisan native:plugin:uninstall nativephp/mobile-device
php artisan native:plugin:uninstall nativephp/mobile-dialog
php artisan native:plugin:uninstall nativephp/mobile-file
php artisan native:plugin:uninstall nativephp/mobile-system

Or remove them directly with Composer if they were never registered in your NativeServiceProvider:

composer remove nativephp/mobile-device nativephp/mobile-dialog nativephp/mobile-file nativephp/mobile-system

No application code changes are required. The Native\Mobile\Facades\{Device, Dialog, File, System} facades and their events (ButtonPressed, etc.) are unchanged. Their docs now live in The Basics section: Device, Dialog, File, and System.

The Vite dev server is now opt-in#

native:run and native:watch no longer start the Vite dev server automatically. If you rely on Vite HMR during development (React/Vue/Tailwind, etc.), add the --vite flag:

php artisan native:watch --vite
php artisan native:run --watch --vite

The old --no-vite flag still exists but is now redundant — Vite is off unless you ask for it. If you have --no-vite in your scripts, you can drop it.

Update your dependency#

"require": {
    "nativephp/mobile": "~3.1.0" 
    "nativephp/mobile": "~4.0.0" 
}

composer update
php artisan native:install --force

For Plugin Developers#

Widen the constraint in your plugin's composer.json to allow the new release:

"require": {
    "nativephp/mobile": "^3.0" 
    "nativephp/mobile": "^3.0|^4.0" 
}

If your plugin depends on any of the conflicting plugins above, remove them from your composer.json's require.