{"id":22751,"library":"vite-plugin-native-modules","title":"vite-plugin-native-modules","description":"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.","status":"active","version":"2.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/biw/vite-plugin-native-modules","tags":["javascript","vite","vite-plugin","plugin","native","modules","node-gyp","native-module","native-addon","typescript"],"install":[{"cmd":"npm install vite-plugin-native-modules","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-native-modules","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-native-modules","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency – plugin requires Vite to function","package":"vite","optional":false}],"imports":[{"note":"Package exports a default function (ESM). Use default import; named import will not work.","wrong":"const { nativeFilePlugin } = require('vite-plugin-native-modules')","symbol":"nativeFilePlugin","correct":"import nativeFilePlugin from 'vite-plugin-native-modules'"},{"note":"Type-only export; use `import type` to avoid runtime import errors.","wrong":"import { NativeFilePluginOptions } from 'vite-plugin-native-modules'","symbol":"type NativeFilePluginOptions","correct":"import type { NativeFilePluginOptions } from 'vite-plugin-native-modules'"},{"note":"The plugin is a function, not a class. Do not instantiate with `new`.","wrong":"import { NativeFilePlugin } from 'vite-plugin-native-modules';\nexport default defineConfig({ plugins: [new NativeFilePlugin()] });","symbol":"defineConfig + plugin","correct":"import { defineConfig } from 'vite';\nimport nativeFilePlugin from 'vite-plugin-native-modules';\nexport default defineConfig({ plugins: [nativeFilePlugin()] });"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport nativeFilePlugin from 'vite-plugin-native-modules';\n\nexport default defineConfig({\n  plugins: [nativeFilePlugin()],\n  build: {\n    rollupOptions: {\n      external: ['electron'], // if using Electron\n    },\n  },\n});\n\n// src/main.ts (after building)\nimport addon from './build/Release/addon.node';\nconsole.log(addon.hello());\n\n// Install plugin: npm install vite-plugin-native-modules","lang":"typescript","description":"Basic setup: add plugin to vite config, import a .node file, and use it."},"warnings":[{"fix":"Set `forced: true` in plugin options when running in dev mode.","message":"Plugin is disabled in dev mode by default (forced: false). Native module imports will fail in vite dev server unless you set forced: true.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Stick with default 'preserve' format unless you have a specific need.","message":"filenameFormat: 'hash-only' option is available since v2.x but may change behavior in future versions.","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"Use `import nativeFilePlugin from 'vite-plugin-native-modules'` instead of `require('vite-plugin-native-modules')`.","message":"v2.0.0 changed the default import and removed CommonJS support. Existing CJS projects must switch to ESM.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your code imports the .node file directly, or configure `additionalNativeFiles` for packages with non-standard extensions.","message":"The plugin only processes .node files imported in JavaScript/TypeScript modules. It does not automatically detect .node files in node_modules unless imported explicitly.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Add `build.rollupOptions.external: ['electron']` in vite config.","message":"When using Electron, the plugin may conflict with Electron's own native module resolution. You might need to externalize 'electron' in rollupOptions.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Install the package: `npm install vite-plugin-native-modules`. Ensure tsconfig.json has `moduleResolution: 'bundler'` or `node16`.","cause":"Package not installed or TypeScript cannot resolve types.","error":"Cannot find module 'vite-plugin-native-modules' or its corresponding type declarations."},{"fix":"Use `nativeFilePlugin()` without `new`.","cause":"Using `new nativeFilePlugin()` instead of calling it as a function.","error":"TypeError: nativeFilePlugin is not a constructor"},{"fix":"Add the plugin to vite config: `import nativeFilePlugin from 'vite-plugin-native-modules'` and add `plugins: [nativeFilePlugin()]`.","cause":"Vite/Rollup cannot parse the .node binary file because the plugin is not loaded or configured.","error":"Module parse failed: Unexpected character '@' (1:0) - file is not a JavaScript module"},{"fix":"Install a compatible Vite version: `npm install vite@^5.0.0` or upgrade/downgrade accordingly.","cause":"Incompatible Vite version installed.","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"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}