fix: configure Prisma for packaged Electron app

[altaskur]

Fix: Configure Prisma for packaged Electron app

• Add node_modules/.prisma to electron-builder files
• Configure PRISMA_QUERY_ENGINE paths for app.asar.unpacked
• Add cross-platform support for query engine detection
• Update build scripts to auto-generate Prisma client

Fixes issue where Prisma cannot find query_compiler_bg.sqlite.mjs when running in production (packaged app)

Description

This hotfix resolves a critical production issue where the packaged Electron application fails to load Prisma's query engine. When the app is packaged with electron-builder and asar, Prisma cannot locate the query engine binaries (query_compiler_bg.sqlite.mjs), causing the application to be completely non-functional in production environments.

The fix configures the correct paths for Prisma's query engine binaries in the app.asar.unpacked directory and ensures all necessary Prisma files are included in the packaged build.

Goal

Fix the "Cannot find query_compiler_bg.sqlite.mjs" error that occurs when running the packaged application in production by properly configuring Prisma query engine paths for electron apps packaged with asar.

Key Changes

• Added runtime configuration in main.ts to detect and set correct PRISMA_QUERY_ENGINE paths when running in packaged mode
• Updated electron-builder configuration to include node_modules/.prisma/**/* in the packaged files
• Modified build scripts (build and dev) to automatically generate Prisma client before compilation
• Implemented cross-platform support for query engine detection (Windows, macOS Intel/ARM64, Linux)
• Enabled asar packaging in electron-builder configuration

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📝 Documentation update
• 🎨 Style/UI changes
• ♻️ Refactoring (no functional changes)
• ⚡ Performance improvement
• ✅ Test updates
• 🔧 Build/configuration changes

Impact Assessment

Database Impact

• No database changes
• New migration(s) included
• Existing data migration required

This fix only affects how Prisma locates its query engine in production. No database schema changes or migrations are included.

Backup Impact

• No impact on backups
• Backup format changed
• Restore compatibility maintained

This fix does not affect backup or restore functionality. Database operations remain unchanged.

Testing

How Has This Been Tested?

• Unit tests
• Integration tests
• Manual testing
• Tested with SonarQube analysis

The fix has been manually tested by building and packaging the application, then running it in a production-like environment to verify database operations work correctly.

Test Steps

1. Run npm run build to compile the application with Prisma client generation
2. Package the application using electron-builder (npm run dist:win for Windows)
3. Install the packaged application in a clean environment (without development dependencies)
4. Launch the application and verify it starts without Prisma-related errors
5. Perform database CRUD operations (create project, add task, create time entry, etc.) to confirm Prisma queries execute successfully
6. Check application logs to ensure no query engine errors appear
7. Test backup and restore functionality to ensure database operations work end-to-end

Test Configuration

• Node version: 20.x
• npm version: 10.x
• Platform tested: Windows

UI Changes

No UI changes. This is a backend/infrastructure fix.

Before

Application would crash or fail to start with console errors:

Error: Cannot find query_compiler_bg.sqlite.mjs
Error: Prisma Client could not locate the Query Engine

After

Application starts normally and all database operations work as expected in the packaged application.

Checklist

• My code follows the project's coding standards
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings or errors
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have run npm run lint and fixed any issues
• I have run npm test and all tests pass
• I have run npm run test:electron and all tests pass
• I have run npm run sonar:check and the analysis passes
• Any dependent changes have been merged and published

Breaking Changes

• This PR contains breaking changes

No breaking changes. This is a hotfix that only affects the production build process and does not change any APIs or user-facing functionality.

Related Issues

Closes #[TBD]
Related to production deployment issues

Additional Context

Technical Background

When Electron packages an application with asar (archive format), Prisma's native query engine binaries cannot be accessed from within the asar archive. Electron-builder has a mechanism to extract certain files to app.asar.unpacked, but Prisma needs to be explicitly told where to find these binaries through environment variables.

Platform-specific Query Engine Files

• Windows: query_engine-windows.dll.node
• macOS Intel: libquery_engine-darwin.dylib.node
• macOS ARM64: libquery_engine-darwin-arm64.dylib.node
• Linux: libquery_engine-debian-openssl-3.0.x.so.node

Why Auto-generate Prisma Client

The build scripts now run npm run prisma:generate before compilation to ensure:

1. The Prisma client is always up-to-date with the schema
2. Query engine binaries are downloaded and available for packaging
3. TypeScript types are generated for type-safe database queries

Files Modified

1. electron/src/main/main.ts (+35 lines)

   • Added Prisma configuration block that runs only in packaged mode
   • Detects platform and architecture
   • Sets PRISMA_QUERY_ENGINE_LIBRARY and PRISMA_QUERY_ENGINE_BINARY environment variables

2. package.json (+5, -3 lines)

   • Added node_modules/.prisma/**/* to electron-builder files array
   • Modified build and dev scripts to include npm run prisma:generate
   • Enabled asar packaging

Reviewer Notes

Critical Testing Points

Please verify:

1. Production build works: Test the packaged .exe (or .dmg/.AppImage), not just npm run dev
2. Database connections succeed: Verify no Prisma-related errors in console
3. CRUD operations function: Test creating/reading/updating/deleting data
4. Cross-platform compatibility: If possible, test on different OS platforms

Why This Is A Hotfix

This issue completely breaks the production application - users cannot use the packaged app at all because database operations fail immediately. This needs to be merged and released as soon as possible.

Future Improvements

Consider adding:

• Automated tests for packaged app functionality
• CI/CD pipeline step to verify packaged build before release
• Error handling for missing query engine with user-friendly message

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud