{"id":12372,"library":"vite-plugin-node","title":"Vite Plugin Node","description":"Vite Plugin Node is a crucial Vite plugin specifically crafted to elevate the development experience for Node.js server applications by seamlessly integrating Hot Module Replacement (HMR). This integration allows developers to harness Vite's renowned speed for compilation and its powerful HMR features directly within their backend services, drastically accelerating iteration cycles during development. The current stable version, 8.0.0, is explicitly designed to be compatible with Vite 8.x.x, reflecting a release cadence that closely mirrors Vite's major version updates. A primary differentiator of this plugin is its extensive, out-of-the-box support for a wide array of popular Node.js frameworks, including Express, Fastify, Koa, and Nest. Beyond these, it also provides the flexibility to define custom request adapters, accommodating virtually any other Node.js framework or server setup. Furthermore, it offers developers a choice in TypeScript compilation, allowing them to utilize either Vite's default Oxc-based transformer or opt for SWC. The SWC option is particularly beneficial for projects that require specific TypeScript features such as decorator metadata. This comprehensive functionality streamlines Node.js backend development, embedding it deeply and efficiently within the modern Vite ecosystem, reducing overhead and maximizing developer productivity.","status":"active","version":"8.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/axe-me/vite-plugin-node","tags":["javascript","vite","vite-plugin","node","hmr","typescript"],"install":[{"cmd":"npm install vite-plugin-node","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-node","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-node","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required only if 'tsCompiler' option is set to 'swc' for TypeScript compilation.","package":"@swc/core","optional":true},{"reason":"Peer dependency; its major version must match vite-plugin-node's major version.","package":"vite","optional":false}],"imports":[{"note":"Primarily designed for ESM. Use named import. CommonJS `require` might lead to issues.","wrong":"const { VitePluginNode } = require('vite-plugin-node');","symbol":"VitePluginNode","correct":"import { VitePluginNode } from 'vite-plugin-node';"}],"quickstart":{"code":"// app.ts (your Node.js server entry file)\nimport express from 'express';\n\nconst app = express();\n\n// Basic route for demonstration\napp.get('/', (req, res) => {\n  res.send('Hello from vite-plugin-node!');\n});\n\n// Your beautiful server logic goes here...\n\n// This named export is crucial for vite-plugin-node to pick up your application.\n// 'viteNodeApp' is the default exportName, but can be configured.\nexport const viteNodeApp = app;\n\n\n// vite.config.ts\nimport { defineConfig } from 'vite';\nimport { VitePluginNode } from 'vite-plugin-node';\n\nexport default defineConfig({\n  // Vite server configuration, e.g., port for your dev server\n  server: {\n    port: 3000\n  },\n  plugins: [\n    // Apply the vite-plugin-node plugin\n    ...VitePluginNode({\n      // Specify the adapter for your Node.js framework (e.g., 'express', 'nest', 'koa', 'fastify')\n      adapter: 'express',\n\n      // Path to your main Node.js server entry file\n      appPath: './app.ts',\n\n      // Optional: The name of the named export for your application instance from appPath.\n      // Defaults to 'viteNodeApp' if not specified.\n      exportName: 'viteNodeApp',\n\n      // Optional: Set to true to initialize your app when the Vite dev server starts.\n      initAppOnBoot: true,\n\n      // Optional: Set to true to automatically reload the app on file changes.\n      reloadAppOnFileChange: true,\n\n      // Optional: Choose TypeScript compiler ('vite' for Oxc or 'swc').\n      // If 'swc' is chosen, you must install '@swc/core' as a dev dependency.\n      tsCompiler: 'vite'\n    })\n  ]\n});\n\n// To run this example:\n// 1. Install dependencies: `npm install express vite vite-plugin-node -D`\n// 2. Add a script to your package.json: `\"dev\": \"vite\"`\n// 3. Create 'app.ts' and 'vite.config.ts' in your project root with the above content.\n// 4. Start the dev server: `npm run dev`","lang":"typescript","description":"Sets up a basic Express.js server with Vite-powered Hot Module Replacement (HMR) using `vite-plugin-node`, demonstrating `vite.config.ts` and the server entry point."},"warnings":[{"fix":"Always consult the version compatibility table in the documentation and upgrade vite-plugin-node to the version matching your Vite major version (e.g., Vite 8.x.x needs vite-plugin-node 8.x.x).","message":"Vite and vite-plugin-node versions are tightly coupled. Upgrading Vite to a new major version (e.g., from 7.x to 8.x) requires a corresponding upgrade of vite-plugin-node to its matching major version.","severity":"breaking","affected_versions":">=3.x"},{"fix":"If configuring 'tsCompiler' to 'swc', ensure you run 'npm install -D @swc/core' in your project.","message":"Using 'tsCompiler: 'swc'' requires manually installing the '@swc/core' peer dependency as a dev dependency. Failing to do so will result in compilation errors.","severity":"gotcha","affected_versions":">=3.x"},{"fix":"Ensure 'exportName' in your vite.config.ts (default 'viteNodeApp') matches the exact named export (e.g., 'export const viteNodeApp = app;') in your server entry file.","message":"The 'exportName' option in the plugin configuration must precisely match the named export of your application instance from the 'appPath' file. A mismatch will prevent the plugin from correctly identifying and loading your server.","severity":"gotcha","affected_versions":">=3.x"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install the required SWC compiler: `npm install -D @swc/core`.","cause":"The 'tsCompiler: 'swc'' option is enabled in vite.config.ts, but the '@swc/core' package is not installed in the project's dev dependencies.","error":"Cannot find module '@swc/core' or similar SWC-related compilation error."},{"fix":"Verify that the 'exportName' (default 'viteNodeApp') in your plugin configuration precisely matches the named export in your server entry file, e.g., `export const viteNodeApp = app;`.","cause":"The 'exportName' option in vite.config.ts does not match the actual named export of your application instance from the specified 'appPath'.","error":"ReferenceError: viteNodeApp is not defined (or similar error indicating the app could not be loaded)."},{"fix":"Ensure your project is configured for ESM (e.g., add `\"type\": \"module\"` to your `package.json`) and use the `import { VitePluginNode } from 'vite-plugin-node';` syntax in your `vite.config.ts`.","cause":"Attempting to use CommonJS `require()` syntax for vite-plugin-node, which is primarily distributed as an ESM package.","error":"ERR_REQUIRE_ESM or TypeError: require is not a function when importing vite-plugin-node."}],"ecosystem":"npm"}