# Native Modules

Read this when adding Electron native dependencies such as `node-pty`, or any package that ships `.node` binaries, helper executables, or rebuild-time headers.

- This repo's `forge.config.ts` uses a deny-by-default `ignore` filter for most `node_modules` content. When adding a native dependency, explicitly allowlist the runtime package and any rebuild-time helper packages it requires (for example `node-addon-api`), or Electron Forge can fail during `Preparing native dependencies` with errors like `Cannot find module 'node-addon-api'`.
- Add native runtime packages to `vite.main.config.mts` `build.rollupOptions.external` so Vite does not bundle them into the main-process build.
- Add native runtime packages to `forge.config.ts` `rebuildConfig.extraModules` so Electron Forge rebuilds them against the packaged Electron version.
- If the package loads helper binaries from disk at runtime (for example `node-pty` loading `spawn-helper` or `winpty-agent` next to its native module), unpack the whole package directory with `packagerConfig.asar.unpackDir`; auto-unpacking `.node` files alone is not enough.
- Windows release builds using `@electron/windows-sign` recursively try to sign `.ps1` scripts in packaged native dependencies. If a bundled dependency includes helper PowerShell files that are not Authenticode-signable (such as `node-pty`'s `deps/winpty/misc/*.ps1`), remove or exclude them before the Forge signing step or `signtool.exe` will fail with `Number of errors: 2`.
- Windows signing can also fail on non-Windows native prebuilds that were unpacked into the app bundle. For `node-pty`, strip Darwin-only artifacts such as `prebuilds/darwin-*` and `bin/*` before signing or `signtool.exe` may fail with `This file format cannot be signed because it is not recognized`.
