Let's get to beta!
- The layers
- Doing some digging
- Two or three copies
- Verbose output
- Check the logs
- Step out
- Start from scratch
- Check your app and PHP
- Still stuck?
#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
andnative: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.
Platform | Location |
---|---|
macOS | ~/Library/Application Support |
Linux | $XDG_CONFIG_HOME or ~/.config |
Windows | %APPDATA% |
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.