Registry / devops / vite-plugin-native-modules

vite-plugin-native-modules

library2.2.1jsnpmunverified

Vite plugin (v2.2.1) for seamless integration of Node.js native modules (.node files) into Vite builds. Supports Electron, node-gyp-build, and bindings package patterns. Offers automatic file hashing, cache busting, and zero-config setup for most use cases. Compatible with Vite 3–7. Key differentiator: resolves native module imports in Vite/Rollup, which unlike Webpack, lack built-in .node file handling. Includes support for NAPI-RS and custom native file extensions since v2.2.0.

devops

npm install vite-plugin-native-modules

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-NATIVE

vite-plugin-native-modules

devopsjavascriptv2.2.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

nativeFilePlugin

✓ import nativeFilePlugin from 'vite-plugin-native-modules'

✗ const { nativeFilePlugin } = require('vite-plugin-native-modules')

Package exports a default function (ESM). Use default import; named import will not work.

type NativeFilePluginOptions

✓ import type { NativeFilePluginOptions } from 'vite-plugin-native-modules'

✗ import { NativeFilePluginOptions } from 'vite-plugin-native-modules'

Type-only export; use `import type` to avoid runtime import errors.

defineConfig + plugin

✓ import { defineConfig } from 'vite'; import nativeFilePlugin from 'vite-plugin-native-modules'; export default defineConfig({ plugins: [nativeFilePlugin()] });

✗ import { NativeFilePlugin } from 'vite-plugin-native-modules'; export default defineConfig({ plugins: [new NativeFilePlugin()] });

The plugin is a function, not a class. Do not instantiate with `new`.

Basic setup: add plugin to vite config, import a .node file, and use it.

// vite.config.ts import { defineConfig } from 'vite'; import nativeFilePlugin from 'vite-plugin-native-modules'; export default defineConfig({ plugins: [nativeFilePlugin()], build: { rollupOptions: { external: ['electron'], // if using Electron }, }, }); // src/main.ts (after building) import addon from './build/Release/addon.node'; console.log(addon.hello()); // Install plugin: npm install vite-plugin-native-modules

Debug

Known issues

gotchaPlugin is disabled in dev mode by default (forced: false). Native module imports will fail in vite dev server unless you set forced: true.

fix

Set `forced: true` in plugin options when running in dev mode.

affects: >=0.0.0

deprecatedfilenameFormat: 'hash-only' option is available since v2.x but may change behavior in future versions.

fix

Stick with default 'preserve' format unless you have a specific need.

affects: >=2.0.0

breakingv2.0.0 changed the default import and removed CommonJS support. Existing CJS projects must switch to ESM.

fix

Use `import nativeFilePlugin from 'vite-plugin-native-modules'` instead of `require('vite-plugin-native-modules')`.

affects: >=2.0.0

gotchaThe plugin only processes .node files imported in JavaScript/TypeScript modules. It does not automatically detect .node files in node_modules unless imported explicitly.

fix

Ensure your code imports the .node file directly, or configure `additionalNativeFiles` for packages with non-standard extensions.

affects: >=0.0.0

gotchaWhen using Electron, the plugin may conflict with Electron's own native module resolution. You might need to externalize 'electron' in rollupOptions.

fix

Add `build.rollupOptions.external: ['electron']` in vite config.

affects: >=0.0.0

Errors

Common errors & fixes

Cannot find module 'vite-plugin-native-modules' or its corresponding type declarations.

Package not installed or TypeScript cannot resolve types.

fix

Install the package: `npm install vite-plugin-native-modules`. Ensure tsconfig.json has `moduleResolution: 'bundler'` or `node16`.

TypeError: nativeFilePlugin is not a constructor

Using `new nativeFilePlugin()` instead of calling it as a function.

fix

Use `nativeFilePlugin()` without `new`.

Module parse failed: Unexpected character '@' (1:0) - file is not a JavaScript module

Vite/Rollup cannot parse the .node binary file because the plugin is not loaded or configured.

fix

Add the plugin to vite config: `import nativeFilePlugin from 'vite-plugin-native-modules'` and add `plugins: [nativeFilePlugin()]`.

Error: The plugin 'vite-plugin-native-modules' is not compatible with your Vite version. Required: ^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0

Incompatible Vite version installed.

fix

Install a compatible Vite version: `npm install vite@^5.0.0` or upgrade/downgrade accordingly.

Upgrade

Version history

2.2.1latest on npm

Audit

Dependencies

viterequiredpeer dependency – plugin requires Vite to function

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/biw/vite-plugin-native-modules ↗

packagehttps://www.npmjs.com/package/vite-plugin-native-modules ↗