esbuild-native-node-modules-plugin

1.0.3 verified Fri May 01 auth: no javascript

A plugin for esbuild that enables bundling of native Node.js modules (.node files). Version 1.0.3 is current. It acts as a node-loader replacement for esbuild, allowing use of native addons in bundled output. Differentiates from general node-loader plugins by being esbuild-native and simple to integrate.

Common errors

error Error: The plugin "nativeNodeModulesPlugin" doesn't have a setup function ↓

cause Importing incorrectly as default export instead of named export.

fix

Use import { nativeNodeModulesPlugin } from 'esbuild-native-node-modules-plugin'

error TypeError: Cannot read properties of undefined (reading 'onResolve') ↓

cause Plugin is not properly registered in esbuild plugins array.

fix

Ensure plugin is added to esbuild config plugins array: plugins: [nativeNodeModulesPlugin]

Warnings

gotcha Platform must be set to 'node' for native modules to work. ↓

fix Set platform option in esbuild config to 'node'.

Install

npm install esbuild-native-node-modules-plugin

yarn add esbuild-native-node-modules-plugin

pnpm add esbuild-native-node-modules-plugin

Imports

nativeNodeModulesPlugin

wrong

const nativeNodeModulesPlugin = require('esbuild-native-node-modules-plugin')

correct

import { nativeNodeModulesPlugin } from 'esbuild-native-node-modules-plugin'

ESM import is preferred if using modules.

nativeNodeModulesPlugin

wrong

const nativeNodeModulesPlugin = require('esbuild-native-node-modules-plugin').default

correct

const { nativeNodeModulesPlugin } = require('esbuild-native-node-modules-plugin')

CommonJS require with destructuring. No default export.

nativeNodeModulesPlugin as nativeNodeModulesPlugin

wrong

import nativeNodeModulesPlugin from 'esbuild-native-node-modules-plugin'

correct

import { nativeNodeModulesPlugin } from 'esbuild-native-node-modules-plugin'

Use named import, not default import.

Quickstart

Shows using the plugin in an esbuild build to support native .node modules.

import { build } from 'esbuild';
import { nativeNodeModulesPlugin } from 'esbuild-native-node-modules-plugin';

build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/bundle.js',
  platform: 'node',
  plugins: [nativeNodeModulesPlugin],
}).catch(() => process.exit(1));