OpenParable
Skip to content
← Back to skills

Electron Native Addon Builder

Development
electron-native-addon-builder

Electron Native Addon Builder is an Agent Skill for development published in the a5c-ai/babysitter repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/a5c-ai/babysitter/blob/HEAD/library/specializations/desktop-development/skills/electron-native-addon-builder/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/electron-native-addon-builder, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

ModuleUse CaseN-API Support
better-sqlite3SQLite databaseYes
sharpImage processingYes
node-ptyTerminal emulationYes
serialportSerial communicationYes
robotjsDesktop automationLimited
node-hidUSB HID devicesYes

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