rollup-plugin-natives

0.7.8 verified Mon Apr 27 auth: no javascript

A Rollup plugin that extracts native .node files from the bundle and copies them to a specified directory, with options for renaming, mapping, and using dlopen or createRequire for ESM. Current stable version is 0.7.8. Released on npm, maintained by @danielgindi. Differentiates from other Rollup native module plugins by supporting node-pre-gyp and bindings integration, providing originTransform for dynamic path resolution, and offering flexible copying and naming via map functions.

Common errors

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

cause Plugin didn't copy the .node file or destDir is incorrect.

fix

Verify copyTo and destDir paths, ensure the plugin runs before bundle generation.

error TypeError: dlopen is not a function ↓

cause dlopen option set to true but the native module expects require().

fix

Set dlopen: false or ensure the module supports dlopen.

Warnings

gotcha Plugin does not handle dynamic require() of .node files that are not statically analyzable. ↓

fix Ensure all native module requires are static strings, or use originTransform to map dynamic paths.

gotcha destDir is relative to the output bundle, not to the project root. ↓

fix Set destDir relative to the output file location (e.g., './libs' if bundle is in 'dist').

gotcha dlopen option must be true if using a file extension other than .node. ↓

fix Set dlopen: true when working with .node files that have a different extension.

gotcha targetEsm option is required for ESM output; without it, createRequire is not used and imports fail. ↓

fix Set targetEsm: true when output format is 'esm' or 'es'.

Install

npm install rollup-plugin-natives

yarn add rollup-plugin-natives

pnpm add rollup-plugin-natives

Imports

default (plugin function)

wrong

const nativePlugin = require('rollup-plugin-natives');

correct

import nativePlugin from 'rollup-plugin-natives';

CommonJS require works but ESM import is recommended.

plugin function (named)

wrong

import { nativePlugin } from 'rollup-plugin-natives';

correct

import { default as nativePlugin } from 'rollup-plugin-natives';

No named export exists; use default import.

TypeScript types

wrong

import { Options } from 'rollup-plugin-natives';

correct

import type { Options } from 'rollup-plugin-natives';

Options type must be imported with type-only import to avoid value import in TS.

Quickstart

Basic Rollup config that extracts native .node files to dist/libs and rewrites requires to point there.

// rollup.config.js
import nativePlugin from 'rollup-plugin-natives';

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'cjs'
  },
  plugins: [
    nativePlugin({
      copyTo: 'dist/libs',
      destDir: './libs',
      dlopen: false,
      targetEsm: false,
      sourcemap: true
    })
  ]
};