How to Build Native Node Prebuilds for Multiple Platforms

Building prebuilds per OS and arch with prebuildify means users install your native addon without needing node-gyp or a C toolchain locally.

Native Node modules otherwise compile on every install. Build prebuilds in an os matrix and ship them so npm install just downloads the matching binary.

Steps

• Add an os matrix over the three runner labels.
• Run prebuildify (or prebuild) to compile the addon for the current platform.
• Upload the prebuilds/ folder and collect it before publishing.

Workflow

jobs:
  prebuild:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx prebuildify --napi --strip
      - uses: actions/upload-artifact@v4
        with:
          name: prebuilds-${{ matrix.os }}
          path: prebuilds/

Gotchas

• Build against N-API (--napi) so one prebuild works across Node major versions.
• For arm64 prebuilds, use a native arm runner or cross-compile, since emulated builds can miss CPU features.

Related guides