Vite Plugin Node

Common errors

• Cannot find module '@swc/core' or similar SWC-related compilation error.

  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.
  fix Install the required SWC compiler: `npm install -D @swc/core`.

• ReferenceError: viteNodeApp is not defined (or similar error indicating the app could not be loaded).

  cause The 'exportName' option in vite.config.ts does not match the actual named export of your application instance from the specified 'appPath'.
  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;`.

• ERR_REQUIRE_ESM or TypeError: require is not a function when importing vite-plugin-node.

  cause Attempting to use CommonJS `require()` syntax for vite-plugin-node, which is primarily distributed as an ESM package.
  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`.

Warnings

• breaking 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.
  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).
• gotcha Using 'tsCompiler: 'swc'' requires manually installing the '@swc/core' peer dependency as a dev dependency. Failing to do so will result in compilation errors.
  Fix: If configuring 'tsCompiler' to 'swc', ensure you run 'npm install -D @swc/core' in your project.
• gotcha 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.
  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.

Install

• npm install vite-plugin-node npm
• yarn add vite-plugin-node yarn
• pnpm add vite-plugin-node pnpm

Imports

• VitePluginNode
  wrong:

  const { VitePluginNode } = require('vite-plugin-node');

  correct:

  import { VitePluginNode } from 'vite-plugin-node';

  Primarily designed for ESM. Use named import. CommonJS `require` might lead to issues.

Quickstart

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.

// app.ts (your Node.js server entry file)
import express from 'express';

const app = express();

// Basic route for demonstration
app.get('/', (req, res) => {
  res.send('Hello from vite-plugin-node!');
});

// Your beautiful server logic goes here...

// This named export is crucial for vite-plugin-node to pick up your application.
// 'viteNodeApp' is the default exportName, but can be configured.
export const viteNodeApp = app;


// vite.config.ts
import { defineConfig } from 'vite';
import { VitePluginNode } from 'vite-plugin-node';

export default defineConfig({
  // Vite server configuration, e.g., port for your dev server
  server: {
    port: 3000
  },
  plugins: [
    // Apply the vite-plugin-node plugin
    ...VitePluginNode({
      // Specify the adapter for your Node.js framework (e.g., 'express', 'nest', 'koa', 'fastify')
      adapter: 'express',

      // Path to your main Node.js server entry file
      appPath: './app.ts',

      // Optional: The name of the named export for your application instance from appPath.
      // Defaults to 'viteNodeApp' if not specified.
      exportName: 'viteNodeApp',

      // Optional: Set to true to initialize your app when the Vite dev server starts.
      initAppOnBoot: true,

      // Optional: Set to true to automatically reload the app on file changes.
      reloadAppOnFileChange: true,

      // Optional: Choose TypeScript compiler ('vite' for Oxc or 'swc').
      // If 'swc' is chosen, you must install '@swc/core' as a dev dependency.
      tsCompiler: 'vite'
    })
  ]
});

// To run this example:
// 1. Install dependencies: `npm install express vite vite-plugin-node -D`
// 2. Add a script to your package.json: `"dev": "vite"`
// 3. Create 'app.ts' and 'vite.config.ts' in your project root with the above content.
// 4. Start the dev server: `npm run dev`