Agent skill

electron-native-addon-builder

Build and bundle native Node.js addons for Electron with proper ABI compatibility, cross-compilation support, and rebuild automation

View SKILL.md on GitHub Repository
Stars 514
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/a5c-ai/babysitter/tree/main/library/specializations/desktop-development/skills/electron-native-addon-builder

SKILL.md

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

json
{
  "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

json
{
  "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)

json
// 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

bash
# 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

yaml
# 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:

javascript
// 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:

json
// 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

bash
# 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

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

Linux from macOS/Windows

bash
# 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:

bash
npx @electron/rebuild -v 28.0.0

Missing Build Tools

Windows: Install Visual Studio Build Tools

bash
npm install -g windows-build-tools

macOS: Install Xcode Command Line Tools

bash
xcode-select --install

Linux: Install build-essential

bash
sudo apt-get install build-essential

Python Version Issues

bash
# 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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

a5c-ai/babysitter

gsd-tools

Central utility skill for GSD operations. Provides config parsing, slug generation, timestamps, path operations, and orchestrates calls to other specialized skills. Acts as the unified entry point that the original gsd-tools.cjs provided via its lib/ modules (commands, config, core, init).

514 31
Explore
a5c-ai/babysitter

model-profile-resolution

Resolve model profile (quality/balanced/budget) at orchestration start and map agents to specific models. Enables cost/quality tradeoffs by selecting appropriate AI models for each agent role.

514 31
Explore
a5c-ai/babysitter

verification-suite

Plan structure validation, phase completeness checks, reference integrity verification, and artifact existence confirmation. Provides the structured verification layer ensuring GSD artifacts are well-formed and complete.

514 31
Explore
a5c-ai/babysitter

state-management

STATE.md reading, writing, and field-level updates. Provides cross-session state persistence via .planning/STATE.md with structured fields for current task, completed phases, blockers, decisions, and quick tasks.

514 31
Explore
a5c-ai/babysitter

git-integration

Git commit patterns, formats, and conventions for GSD methodology. Provides atomic commits per task, structured commit messages, planning file commits, branch management, and milestone tag operations.

514 31
Explore
a5c-ai/babysitter

frontmatter-parsing

YAML frontmatter parsing and manipulation for .planning/ documents. Provides read, write, update, query, and validation operations on frontmatter blocks in GSD markdown artifacts.

514 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results