vite-plugin-native-modules

2.2.1 verified Mon Apr 27 auth: no javascript

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.

Common errors

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

cause 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.

error TypeError: nativeFilePlugin is not a constructor ↓

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

fix

Use nativeFilePlugin() without new.

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

cause 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 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 ↓

cause Incompatible Vite version installed.

fix

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

Warnings

gotcha Plugin 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.

deprecated filenameFormat: '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.

breaking v2.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')`.

gotcha The 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.

gotcha When 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.

Install

npm install vite-plugin-native-modules

yarn add vite-plugin-native-modules

pnpm add vite-plugin-native-modules

Imports

nativeFilePlugin

wrong

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

correct

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

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

type NativeFilePluginOptions

wrong

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

correct

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

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

defineConfig + plugin

wrong

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

correct

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

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

Quickstart

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