Published Electron project: .env.production is excluded by Laravel's default .gitignore, so CI builds ship an app that crashes on launch

[NicolasMica]

What were you trying to do?

Build a .dmg in CI from a repository where the Electron project has been published with php artisan native:install --publish and committed to version control.

What happened?

The build succeeds, every artifact is produced and signed, and the resulting .app dies immediately on launch:

Uncaught Exception:
TypeError [ERR_INVALID_ARG_TYPE]: The "paths[1]" argument must be of type string. Received undefined
    at Object.resolve (node:path:1272:7)
    at file:///Applications/<App>.app/Contents/Resources/app.asar/out/main/index.js:2771:24

Extracting the bundle from the shipped asar shows why:

const buildPath = path.resolve(
  import.meta.dirname,
  void 0
);

MAIN_VITE appears zero times in the packaged bundle.

Root cause

resources/electron/.env.production is the only place MAIN_VITE_NATIVEPHP_BUILD_PATH is defined for a production build, and Laravel's own skeleton .gitignore excludes it. laravel/laravel's .gitignore has .env.production on line 5, unanchored, so it matches nativephp/electron/.env.production at any depth:

$ git check-ignore -v nativephp/electron/.env.production
.gitignore:19:.env.production	nativephp/electron/.env.production

The file is therefore never committed. actions/checkout runs git clean -ffdx, and native:build does not run native:install, so CI builds without it. Vite then does what it documents: "import.meta.env.NON_EXISTENT in JS … is replaced as undefined" — silently, with no warning and no build error. electron-vite build runs in production mode, so .env.development is never consulted as a fallback.

Local native:run is completely unaffected, because dev mode loads .env.development, where the value is expanded from NATIVEPHP_BUILD_PATH. So this only ever appears in a packaged build, and only for people whose Electron project came from a clean checkout.

How to reproduce the bug

1. php artisan native:install --publish
2. git add nativephp/electron && git commit — note that nativephp/electron/.env.production is silently not staged.
3. Clone the repository fresh (or run git clean -ffdx), then php artisan native:build mac arm64.
4. Launch the built .app. It crashes with ERR_INVALID_ARG_TYPE before the PHP runtime starts.

Suggested fix

Don't make the packaged app's ability to find itself depend on a dotfile surviving version control. Defaulting the value in resources/electron/src/main/index.js makes the failure impossible:

const buildPath = path.resolve(
    import.meta.dirname,
    import.meta.env.MAIN_VITE_NATIVEPHP_BUILD_PATH || '../../../build',
);

(|| rather than ??: dotenv expansion of an unset ${NATIVEPHP_BUILD_PATH} yields '', and path.resolve() treats '' as a no-op rather than throwing.)

.env.production can stay exactly as it is — this just stops its absence from being fatal. Worth considering alongside it: CreatesElectronProject could write a nativephp/electron/.gitignore entry, or the installer could warn when the file it just wrote is git-ignored.

This affects every Laravel application that publishes the Electron project and commits it, which makes it a fairly wide blast radius for a failure that is invisible until a user double-clicks the app.

Which operating systems have you seen this occur on?

macOS

Notes

• NativePHP Desktop: 2.1
• PHP: 8.5
• electron-vite: 4.x / Vite: 7.3.1

Related in symptom only (packaged-app-only main process crash, invisible in dev): #83.

[simonhamp]

Yep this looks like it should be fixed. Would you mind raising a PR?