네이티브 모듈 — Node.js C++ 애드온과 node-gyp

"네이티브 모듈은 JavaScript만으로는 불가능한 시스템 레벨 작업을 C++로 처리" — 성능이 중요하거나 OS API를 직접 호출해야 할 때 사용합니다.

네이티브 모듈이란

Node.js 네이티브 모듈은 C/C++로 작성된 바이너리 애드온입니다. .node 확장자로 컴파일되어 require()로 불러옵니다.

대표적인 네이티브 모듈

모듈	용도
`better-sqlite3`	SQLite 데이터베이스
`sharp`	이미지 처리
`node-pty`	터미널 에뮬레이션
`keytar`	OS 키체인 접근
`node-hid`	USB HID 장치 통신

ABI 호환성 문제

Electron은 자체 Node.js를 내장하고 있어서, 시스템에 설치된 Node.js와 **ABI(Application Binary Interface)가 다릅니다 **.

BASH

# 시스템 Node.js로 빌드한 모듈은 Electron에서 동작하지 않을 수 있음
npm install better-sqlite3
# → 시스템 Node.js ABI로 빌드됨

# Electron용으로 재빌드 필요
npx electron-rebuild

electron-rebuild

BASH

# electron-rebuild 설치
npm install @electron/rebuild --save-dev

# 모든 네이티브 모듈을 Electron 버전에 맞게 재빌드
npx electron-rebuild

# 특정 모듈만 재빌드
npx electron-rebuild -o better-sqlite3

# 특정 Electron 버전용으로 빌드
npx electron-rebuild -v 28.0.0

package.json에 자동 빌드 추가

JSON

{
  "scripts": {
    "postinstall": "electron-rebuild",
    "rebuild": "electron-rebuild"
  }
}

N-API (Node-API) 사용

N-API는 ABI 안정성을 보장하는 API입니다. N-API로 작성된 모듈은 Node.js/Electron 버전이 바뀌어도 재빌드 없이 동작할 수 있습니다.

JAVASCRIPT

// N-API 기반 모듈 예시 — better-sqlite3는 N-API를 사용합니다
const Database = require('better-sqlite3');
const db = new Database('app.db');

const stmt = db.prepare('SELECT * FROM users WHERE id = ?');
const user = stmt.get(1);

N-API 여부 확인

패키지의 package.json에서 napi_versions 필드가 있으면 N-API를 사용합니다.

Electron Forge에서 네이티브 모듈

JAVASCRIPT

// forge.config.js
module.exports = {
  packagerConfig: {
    asar: true,
    // 네이티브 모듈은 asar에 포함하지 않기
    asarUnpack: [
      'node_modules/better-sqlite3/**',
      'node_modules/sharp/**',
    ],
  },
  hooks: {
    packageAfterPrune: async (config, buildPath) => {
      // 네이티브 모듈 재빌드
      const { rebuild } = require('@electron/rebuild');
      await rebuild({ buildPath, electronVersion: '28.0.0' });
    },
  },
};

트러블슈팅

빌드 환경 요구사항

BASH

# macOS: Xcode Command Line Tools
xcode-select --install

# Windows: Visual Studio Build Tools
npm install --global windows-build-tools

# Linux: build-essential
sudo apt install build-essential python3

일반적인 에러

PLAINTEXT

Error: The module was compiled against a different Node.js version
→ electron-rebuild 실행 필요

Error: Cannot find module 'better-sqlite3'
→ asar 안에 네이티브 모듈이 있으면 asarUnpack 설정 필요

면접 포인트 정리

Electron은 자체 Node.js를 내장하므로 네이티브 모듈 ABI 호환성 주의
electron-rebuild로 Electron 버전에 맞는 재빌드 필수
N-API 기반 모듈은 ABI 안정성 보장 (재빌드 불필요할 수 있음)
네이티브 모듈은 asarUnpack에 추가해야 패키징 후에도 동작
빌드 환경(컴파일러, Python 등)이 갖춰져야 함

네이티브 모듈을 다뤘으면, 다음은 SQLite와 로컬 데이터베이스 활용을 알아봅시다.