Development


Developing your NativePHP apps can be done in the browser, using workflows with which you're already familiar.

This allows you to iterate rapidly on parts like the UI and major functionality, even using your favorite tools for testing etc.

But when you want to test native features, then you must run your app on a real/emulated device.

Whether you run your native app on an emulated or real device, it will always require compilation after changes have been made.

#Build your frontend

If you're using Vite or similar tooling to build any part of your UI (e.g. for React/Vue, Tailwind etc), you'll need to run your asset build command before compiling your app.

#Inertia on iOS

Due to the way your apps are configured to work on iOS, we need to patch the Axios package to make Inertia work.

We've tried to make this as straightforward as possible. Simply run:

Copied!
php artisan native:patch-inertia

This will backup your current vite.config.js and replace it with one that 'fixes' Axios.

You will just need to copy over any specific config (plugins etc) from your old Vite config to this new one.

Once that's done, you'll need to adjust your Vite build command for when you're creating iOS builds. Only for iOS builds. (If you try to run these builds on Android they probably won't work.)

Add the --mode=ios to your build command. Run it before compiling your app for iOS. Here's an example using npm:

Copied!
npm run build -- --mode=ios

#Compile your app

To compile and run your app, simply run:

Copied!
php artisan native:run --build=debug

This single command takes care of everything and allows you to run new builds of your application without having to learn any new editors or platform-specific tools.

#Working with Xcode or Android Studio

On occasion, it is useful to compile your app from inside the target platform's dedicated development tools, Android Studio and Xcode.

If you're familiar with these tools, you can easily open the projects using the following Artisan command:

Copied!
php artisan native:open

#Hot Reloading (Experimental)

We've tried to make compiling your apps as fast as possible, but when coming from the 'make a change; hit refresh'-world of PHP development that we all love, compiling apps can feel like a slow and time-consuming process.

So we've released an early version of hot reloading, which aims to make your development experience feel just like home.

You can enable hot reloading by adding the --watch flag when running the native:run command:

Copied!
php artisan native:run --watch

This is useful during development for quickly testing changes without re-compiling your entire app. When you make changes to any files in your Laravel app, the web view will be reloaded and your changes should show almost immediately.

#Caveats

For now, hot reloading only works in emulators, not on real devices.

Also, it's currently best suited for Blade and Livewire applications. It doesn't work so well if you're also trying to hot reload compiled frontends using something like Vite's hot reloading.

#Releasing

To prepare your app for release, you should set the version number to a new version number that you have not used before and increment the build number:

Copied!
NATIVEPHP_APP_VERSION=1.2.3
NATIVEPHP_APP_VERSION_CODE=48

#Versioning

You have complete freedom in how you version your applications. You may use semantic versioning, codenames, date-based versions, or any scheme that works for your project, team or business.

Remember that your app versions are usually public-facing (e.g. in store listings and on-device settings and update screens) and can be useful for customers to reference if they need to contact you for help and support.

The build number is managed via the NATIVEPHP_APP_VERSION key in your .env.

#Build numbers

Both the Google Play Store and Apple App Store require your app's build number to increase for each release you submit.

The build number is managed via the NATIVEPHP_APP_VERSION_CODE key in your .env.

#Run a release build

Then run a release build:

Copied!
php artisan native:run --build=release

This builds your application with various optimizations that reduce its overall size and improve its performance, such as removing debugging code and unnecessary features (i.e. Composer dev dependencies).

You should test this build on a real device. Once you're happy that everything is working as intended you can then submit it to the stores for approval and distribution.