#

When things go wrong

Building native applications is a complex task with many moving parts. There will be errors, crashes and lots of head-scratching.

NativePHP works to hide much of the complexity, but sometimes you will need go under the hood to find out what's really going on.

Remember that NativePHP is a relatively thin layer above a whole ocean of dependencies and tools that are built and maintained by many developers outside the NativePHP team.

This means that while some issues can be solved within NativePHP it's also very likely that the problem lies elsewhere.

#

The layers

• Your application, built on Laravel, using your local installations of PHP & Node.
• NativePHP's development tools (native:serve and native:build) manage the Electron/Tauri build processes - this is what creates your Application Bundle.
• NativePHP moves the appropriate version of a statically-compiled binary of PHP into your application's bundle - when your app boots, it's this version of PHP that is being used to execute your PHP code, not your system's version of PHP.
• Electron & Tauri use suites of platform-specific build tools and dependencies - Electron's ecosystem is mostly Javascript based, Tauri's is mostly Rust based. Much of this will be hidden away in your vendor directory.
• The operating system (OS) and its architecture (arch) - you can't build an application for one architecture and distribute it to a different OS/arch. It won't work. You must build your application to match the OS+arch combination where you want it to run.

While you are not expected to know in-depth how all of these layers work and fit together, some familiarity with what's going on will help you find the root cause of issues and be able to raise meaningful tickets with the right people.

#

Doing some digging

Here are some tips for debugging:

#

Two or three copies

Remember that when a build is generated (dev or prod), your whole Laravel application is copied into the build folder.

The dev build copy is stored in vendor (holy inception, Batman!).

Prod builds get packed in the dist folder.

This means there are at least 2 versions of your code that could be running depending on what you're doing: the hot code that you edit in your IDE (your 'development environment') and the bundle code that actually gets executed when your app runs in either a dev build or a prod build.

Having a clear understanding about what context you're in when issues occur will help you to solve the problem faster.

#

Verbose output

Use -v, -vv or -vvv when running native:serve or native:build as this will provide more detail as to what's happening at each stage of a process.

#

Check the logs

Logs generated by running builds of your application are stored in {appdata}/storage/logs/.

Logs generated when running Artisan commands in your development environment are in storage/logs/ (default Laravel).

#

Step out

Try running the step that's failing outside of the runtime environment. Reduce the layers of abstraction to identify or rule out environment-specific complications.

#

Start from scratch

dist

Don't be afraid to delete builds and start again! The dist folder in your application's root may sometimes get into an unusual state and just needs wiping out.

AppData

The appdata directory is where your application's database, logs, and other application-specific items are stored. This is a reliable place to store data and files that your application needs to function outside of the app bundle and without cluttering your user's home directory or other personal folders.

When testing prod builds, the appdata directory will be created on your machine, allowing you to fully mimic an end-user experience.

In some cases, you may need to wipe this folder and then re-run your app.

Database

Try completely refreshing your app's prod database:

1php artisan native:migrate:fresh

Processes

Make sure there are no lingering processes. Check your Activity Monitor/Task Manager to find stray processes from your app that may hang around after a build has failed, and force them to quit.

#

Check your app and PHP

Errors that occur in PHP execution during the application's boot-up sequence can cause the app to crash before it even starts.

A 500 error in your application code, for example, may prevent the main window from showing, but would leave the runtime's shell process running.

Try booting your application in a standard browser to see if there are any errors when hitting its entrypoint URL. If you're using Laravel Herd, for example, move your app development environment into your Herd root folder and go to http://{your-app-folder-name}.test/ in your favorite browser.

Also make sure that the PHP version in the bundle is the same as the one you have installed on your machine, i.e. if you're running PHP8.2 on your machine, the PHP binary that is moved into the dist folder should be PHP8.2 for your current OS+arch.

Checking this will also prove that the executable itself is stable:

For dev builds:

macOS & Linux:

1/path/to/your/app/vendor/nativephp/electron/resources/js/resources/php/php -v

Windows:

1C:\path\to\your\app\vendor\nativephp\electron\resources\js\resources\php\php.exe -v

For production builds:

macOS:

1/path/to/your/app/dist/{os+arch}/AppName/Contents/Resources/app.asar.unpacked/resources/php/php -v

Windows:

1C:\path\to\your\app\dist\win-unpacked\resources\app.asar.unpacked\resources\php\php.exe -v

#

Still stuck?

If you've found a bug, please open an issue on GitHub.

There's also Discussions and Discord for live chat.

Come join us! We want you to succeed.