rollup-plugin-native

1.2.16 verified Mon Apr 27 auth: no javascript

A Rollup plugin that enables importing native .node modules (N-API addons) by resolving platform-specific binary paths during bundling. Version 1.2.16, last updated in 2024, with low release cadence (no breaking changes in recent versions). It uses substitution patterns like ${nodePlatform} and ${nativeArchitecture} to dynamically select the correct precompiled binary for the current OS/arch, avoiding the need for node-gyp at runtime. Differentiators: simplifies cross-platform native module bundling without manual conditional requires, and integrates directly into Rollup's plugin system. No other known alternative for Rollup-focused native module import.

Common errors

error Error: Cannot find module '../module.node' ↓

cause platformName pattern does not match the actual file path

fix

Verify platformName template resolves correctly; check process.platform() and process.arch() values.

error TypeError: native is not a function ↓

cause Named import used instead of default import

fix

Use default import: import native from 'rollup-plugin-native'

error (!) Plugin native: Options object is required ↓

cause Plugin instantiated without options but platformName is required

fix

Pass an options object with a 'platformName' property to native().

error Error: Rollup plugin native requires Rollup >=3.0.0 ↓

cause Using an older version of Rollup

fix

Upgrade Rollup to 3.x or later: npm install rollup@latest --save-dev

Warnings

gotcha Format 'cfs' in documentation is a typo; use 'cjs' for CommonJS output. ↓

fix Use output.format: 'cjs' instead of 'cfs'.

gotcha Dynamic require of .node files may not work in all Rollup output formats (e.g., esm). ↓

fix Ensure output format is 'cjs' when using native modules, or use plugin options to generate conditional require.

deprecated Substitution ${basename} strips .node extension; ensure paths are correct. ↓

fix Use ${basename} without .node in the path template, as the extension is handled internally.

breaking The plugin only supports Rollup >=3.0.0; older versions may fail. ↓

fix Upgrade Rollup to version 3 or later.

Install

npm install rollup-plugin-native

yarn add rollup-plugin-native

pnpm add rollup-plugin-native

Imports

default (native)
wrong
```
const native = require('rollup-plugin-native')
```
correct
```
import native from 'rollup-plugin-native'
```
ESM-only package; CommonJS require() will work but is not recommended for Rollup configs.
native
wrong
```
import { native } from 'rollup-plugin-native'
```
correct
```
import native from 'rollup-plugin-native'
```
The plugin exports a default function, not a named export. Use default import.
RollupPluginNativeOptions
wrong
```
undefined
```
correct
```
/** @type {import('rollup-plugin-native').PluginOptions} */
```
TypeScript types may not be shipped; use JSDoc or custom type definitions.

Quickstart

Configures Rollup to resolve native .node modules with platform-specific binary paths using substitution variables.

// rollup.config.js
import native from 'rollup-plugin-native';

export default {
  input: 'src/index.js',
  output: {
    dir: 'dist',
    format: 'cjs'
  },
  plugins: [
    native({
      platformName: 'precompiled/${nodePlatform}-${nodeArchitecture}/native.node'
    })
  ]
};