Agent Skills: electron-native-addon-builder

electron-native-addon-builder

Build and bundle native Node.js addons for Electron with proper ABI (Application Binary Interface) compatibility. This skill handles the complexity of native module compilation, cross-platform building, and ensuring modules work correctly with Electron's Node.js version.

Capabilities

• Configure electron-rebuild for native module compilation
• Set up node-gyp with Electron headers
• Handle cross-platform compilation (Windows, macOS, Linux)
• Manage ABI compatibility between Electron and native modules
• Configure prebuild/prebuild-install for binary distribution
• Set up N-API modules for version-independent builds
• Handle architecture-specific builds (x64, arm64, ia32)
• Integrate with electron-builder for packaging

Input Schema

{
  "type": "object",
  "properties": {
    "projectPath": {
      "type": "string",
      "description": "Path to the Electron project root"
    },
    "nativeModules": {
      "type": "array",
      "description": "List of native modules to handle",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "version": { "type": "string" },
          "source": { "enum": ["npm", "local", "github"] }
        }
      }
    },
    "electronVersion": {
      "type": "string",
      "description": "Target Electron version"
    },
    "targetPlatforms": {
      "type": "array",
      "items": { "enum": ["win32", "darwin", "linux"] }
    },
    "targetArchitectures": {
      "type": "array",
      "items": { "enum": ["x64", "arm64", "ia32"] }
    },
    "useNAPI": {
      "type": "boolean",
      "description": "Use N-API for version-independent builds",
      "default": true
    },
    "prebuildConfig": {
      "type": "boolean",
      "description": "Generate prebuild configuration",
      "default": false
    }
  },
  "required": ["projectPath"]
}

Output Schema

{
  "type": "object",
  "properties": {
    "success": { "type": "boolean" },
    "configuration": {
      "type": "object",
      "properties": {
        "electronRebuild": { "type": "object" },
        "nodeGyp": { "type": "object" },
        "packageJson": { "type": "object" }
      }
    },
    "scripts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "command": { "type": "string" }
        }
      }
    },
    "warnings": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["success"]
}

Configuration Methods

electron-rebuild (Recommended)

// package.json
{
  "scripts": {
    "postinstall": "electron-rebuild",
    "rebuild": "electron-rebuild -f -w native-module-name"
  },
  "devDependencies": {
    "@electron/rebuild": "^3.6.0"
  }
}

node-gyp with Electron Headers

# Set Electron headers for node-gyp
export npm_config_target=28.0.0
export npm_config_arch=x64
export npm_config_target_arch=x64
export npm_config_disturl=https://electronjs.org/headers
export npm_config_runtime=electron
export npm_config_build_from_source=true

npm install native-module

electron-builder Integration

# electron-builder.yml
npmRebuild: true
buildDependenciesFromSource: true
nodeGypRebuild: false

asarUnpack:
  - "**/*.node"
  - "**/node_modules/native-module/**"

N-API Configuration

N-API provides ABI stability across Node.js versions:

// binding.gyp for N-API module
{
  "targets": [
    {
      "target_name": "native_module",
      "sources": ["src/native_module.cc"],
      "include_dirs": [
        "<!@(node -p \"require('node-addon-api').include\")"
      ],
      "dependencies": [
        "<!(node -p \"require('node-addon-api').gyp\")"
      ],
      "defines": ["NAPI_VERSION=8", "NAPI_DISABLE_CPP_EXCEPTIONS"]
    }
  ]
}

Prebuild Configuration

For distributing prebuilt binaries:

// package.json
{
  "scripts": {
    "prebuild": "prebuild -t 28.0.0 -r electron -a x64 -a arm64",
    "prebuild-upload": "prebuild --upload-all $GITHUB_TOKEN"
  },
  "devDependencies": {
    "prebuild": "^12.1.0",
    "prebuild-install": "^7.1.1"
  }
}

Cross-Compilation

Windows from macOS/Linux

# Using electron-rebuild with wine
npx @electron/rebuild --platform=win32 --arch=x64

# Or with prebuild
prebuild -t 28.0.0 -r electron --platform=win32 --arch=x64

macOS ARM64 from x64

# Requires Xcode and arm64 toolchain
npx @electron/rebuild --arch=arm64

Linux from macOS/Windows

# Using Docker
docker run -v $(pwd):/project electron-builder-linux \
  npx @electron/rebuild --platform=linux --arch=x64

Common Native Modules

| Module | Use Case | N-API Support | |--------|----------|---------------| | better-sqlite3 | SQLite database | Yes | | sharp | Image processing | Yes | | node-pty | Terminal emulation | Yes | | serialport | Serial communication | Yes | | robotjs | Desktop automation | Limited | | node-hid | USB HID devices | Yes |

Troubleshooting

ABI Mismatch Error

Error: The module was compiled against a different Node.js version

Solution: Rebuild with correct Electron version:

npx @electron/rebuild -v 28.0.0

Missing Build Tools

Windows: Install Visual Studio Build Tools

npm install -g windows-build-tools

macOS: Install Xcode Command Line Tools

xcode-select --install

Linux: Install build-essential

sudo apt-get install build-essential

Python Version Issues

# Specify Python version for node-gyp
npm config set python /usr/bin/python3

Best Practices

1. Use N-API when possible: Provides version-independent binaries
2. Prebuild binaries: Avoid compilation on user machines
3. Test all platforms: Native modules behave differently per OS
4. Pin Electron version: Ensure ABI compatibility
5. Exclude from ASAR: Native modules must be unpacked
6. Use electron-rebuild: Handles headers automatically

Related Skills

• electron-builder-config - Package native modules correctly
• electron-main-preload-generator - Secure native module usage
• cross-platform-test-matrix - Test native modules across platforms

Related Agents

• electron-architect - Architecture for native modules
• desktop-ci-architect - CI/CD for native module builds