Extra files

[simonhamp]

This build setting allows the developer to add arbitrary files (even pre-compiled executables) into their NativePHP application.

They just need to live in a new folder at the root of your project called extras/ and they will be copied into place.

It also adds the relevant environment to expose the extras path inside the distributed application to the PHP side.

Note: if shipping binaries here, it's the developer's responsibility to ship and execute the appropriate binary for the user's platform.

[gwleuverink]

Linked: NativePHP/laravel#635

@simonhamp Is this ready for testing?

Todo:

• Add to kitchen-sink
• Documentation

[gwleuverink]

Jotted down some docs for your review NativePHP/nativephp.com#181

[simonhamp]

@simonhamp Is this ready for testing?

@gwleuverink should be! I don't think we need an example in the kitchen sink for this to be released. Thanks for doing the docs! 🙏🏼

[gwleuverink]

I ran into something weird.

After changing to this feature branch I wasn't able to run artisan native:installanymore. It complained about an import in the postinstall script.

I had to update the file extension from resources/js/electron-builder.js to .mjs.

After this everything installs without issues & the plugin builds like usual.

The strange thing is I don't see any changes in this PR that should could have caused this. Again, on the main branch native:install works as expected.

@simonhamp does native:install (or npm i from the resources/js directory) work for you?

I've tried with node 22 & 20. Both give the same error.

> NativePHP@1.0.0 postinstall
> node ./node_modules/electron-builder/cli.js install-app-deps

  • electron-builder  version=26.0.15
  ⨯ Unable to `require`  moduleName=/Users/gwleuverink/Code/php/nativephp/electron/resources/js/electron-builder.js message=Unexpected module status 5. Cannot require() ES Module /Users/gwleuverink/Code/php/nativephp/electron/resources/js/electron-builder.js because it is not yet fully loaded. This may be caused by a race condition if the module is simultaneously dynamically import()-ed via Promise.all(). Try await-ing the import() sequentially in a loop instead. (from /Users/gwleuverink/Code/php/nativephp/electron/resources/js/node_modules/app-builder-lib/out/util/resolve.js)
This is caused by either a bug in Node.js or incorrect usage of Node.js internals.
Please open an issue with this stack trace at https://github.com/nodejs/node/issues

[gwleuverink]

I see now the build & test actions have the same problem. The change to .mjs suggested above will likely fix it

[simonhamp]

Thanks @gwleuverink - if this is working for you now, do you fancy approving and I'll get this released

[gwleuverink]

The npm install issue is resolved.

The build action fails, but this likely is due to the update to the upgrade to v6 of stefanzweifel/git-auto-commit-action

stefanzweifel/git-auto-commit-action#383

I'll add the workaround suggested in the thread.

[gwleuverink]

The suggested fix didn't work. I've reverted auto-commit-action back to v5

[gwleuverink]

Thanks @gwleuverink - if this is working for you now, do you fancy approving and I'll get this released

Absolutely. I'm testing it right now. Can you clarify something for me? I've done the following:

1. checked out both feature branches
2. added a file in {project-root}/extras
3. run composer native:dev

Then, when listing the contents of the storage driver it's empty.

Storage::disk('extras')->listContents('')->toArray(); // No files in here

Turns out the extras disk is pointing to ~/Code/php/nativephp/electron/extras. Which is where the cloned electron repo lives.

Any idea? I was expecting it to be ~/Code/php/nativephp/playground/extras

[gwleuverink]

Follow-up:

1. The earlier fix (rename from .js to .mjs) does fix the npm install issue, but causes app builds not to be copied to the dist folder. I'll revisit this tomorrow.

2. When reading the extras disk in a build I get the following error:

[2025-07-15 21:29:03] production.ERROR: Unable to create a directory at /Users/gwleuverink/Code/php/nativephp/playground/dist/mac-arm64/Laravel.app/Contents/Resources/app.asar/nativephp/extras. (View: /Users/gwleuverink/Code/php/nativephp/playground/dist/mac-arm64/Laravel.app/Contents/Resources/app.asar.unpacked/resources/app/resources/views/welcome.blade.php) 

Note I'm not writing to the disk, this is thrown by the code sample from my previous comment

[gwleuverink]

It's a head scratcher. It's explained in this issue: electron-userland/electron-builder#8389

Because this package type module is defined in package.json, all .js files are treated as ES modules, but electron-builder's dependency read-config-file tries to require() them as CommonJS modules, which fails.

Updating electron-builder config to be .mjs fixes it, but the .mjs extension is not detected in the builder config discovery. The fix here is we need to pass the config file to the build commands manually. See 6043353

[gwleuverink]

I installed the electron package from a symlinked directory.
The original join(app.getAppPath(), '..', '..', 'extras') pointed to a wrong relative path

Using APP_PATH makes this consistent no matter how you structure your dev setup

[gwleuverink]

The original join(app.getAppPath(), 'nativephp', 'extras')
pointed to playground.app/Contents/Resources/app.asar/nativephp/extras

Electron builder automatically the extra files in playground.app/Contents/extras.
Using process.resourcesPath instead points it to the right place

[gwleuverink]

We don't need to pack it up in the archive. Otherwise the extra files will be included in the app twice

[gwleuverink]

Everything is working for me now 👌🏻

[simonhamp]

Great work @gwleuverink - feel free to review and merge