electron-native-modules

# Electron Native Modules Skill

Native modules require special handling in Electron because they must be compiled for Electron's Node.js version, not the system Node.js.

## Common Native Modules

| Module | Purpose | Special Notes |
|--------|---------|---------------|
| `better-sqlite3` | SQLite database | Most common, requires rebuild |
| `sharp` | Image processing | Large, multi-platform binaries |
| `keytar` | OS keychain access | Security-sensitive |
| `node-pty` | Terminal emulation | Platform-specific |
| `serialport` | Serial port access | Hardware access |

## Bundler Configuration

### esbuild (Recommended)

Native modules MUST be external - they cannot be bundled:

```bash
# Build command
esbuild src/server/index.ts \
  --bundle \
  --platform=node \
  --format=cjs \
  --outfile=dist/server/index.cjs \
  --external:better-sqlite3 \
  --external:sharp \
  --external:keytar \
  --external:electron
```

### package.json script

```json
{
  "scripts": {
    "build:server": "esbuild src/server/index.ts --bundle --platform=node --format=cjs --outfile=dist/server/index.cjs --external:better-sqlite3 --external:sharp --external:keytar",
    "electron:build": "esbuild electron/*.ts --bundle --platform=node --format=cjs --outdir=electron-dist --out-extension:.js=.cjs --external:electron --external:keytar --external:better-sqlite3 --external:sharp"
  }
}
```

## electron-builder Configuration

```javascript
// electron-builder.config.cjs
module.exports = {
  appId: 'com.yourcompany.yourapp',
  productName: 'Your App',

  // CRITICAL: Include native modules in the app
  files: [
    'dist/**/*',
    'electron-dist/**/*',
    'public/**/*',
    'package.json',
    // Native modules need their binary files
    'node_modules/better-sqlite3/**/*',
    'node_modules/keytar/**/*',
    'node_modules/sharp/**/*',
    // Also include their dependencies
    'node_modules/bindings/**/*',
    'node_modules/file-uri-to-path/**/*',
    'node_modules/prebuild-install/**/*',
  ],