Vite Live Preview Plugin

0.4.0 verified Sat Apr 25 auth: no javascript

vite-live-preview is a Vite plugin designed to provide a live preview server specifically for Vite builds executed with the `--watch` flag. Unlike the standard `vite dev` server, which prioritizes Hot Module Replacement (HMR) for rapid development, this plugin focuses on serving a production-like build output, automatically reloading the browser page whenever a rebuild completes. The current stable version is 0.4.0, and the project appears actively maintained on GitHub, with recent updates. A key differentiator is its explicit non-support for HMR, making it suitable for scenarios where a full page reload is acceptable or preferred, or when simulating a built artifact in a watch mode. It allows for detailed configuration of the preview server, including port settings, reload delays, and handling of complex network setups like reverse proxies via a `clientPort` option. Developers should note that Vite plugins configured in the main `vite.config.ts` are not automatically inherited by the preview server and must be re-added via the plugin's `config` option if needed.

Common errors

error HMR not working / Changes not updating instantly ↓

cause The `vite-live-preview` plugin is designed for full page reloads, not Hot Module Replacement (HMR).

fix

For HMR, use Vite's standard development server (npx vite dev). vite-live-preview is for watchable builds with full page reloads.

error My Vite plugins (e.g., Vue plugin, React plugin) are not active in the preview server. ↓

cause The `vite-live-preview` server does not inherit plugins from the main `vite.config.ts` automatically.

fix

You must explicitly re-add any required plugins for the preview server within the config option of the preview() plugin, e.g., preview({ config: { plugins: [vue()] } }).

error Vite build completes, but no preview server starts. ↓

cause The `vite-live-preview` plugin requires the `vite build` command to be run with the `--watch` flag.

fix

Ensure you are using npx vite build --watch to start both the build watcher and the preview server.

error WebSocket connection failed during reload or 'vite:ws:disconnect' error in console. ↓

cause The browser client might be trying to connect to an incorrect WebSocket port, often due to a reverse proxy remapping ports.

fix

If your preview server is behind a reverse proxy, configure the reload.clientPort option in your vite-live-preview plugin settings to specify the correct port for the WebSocket client to connect to.

Warnings

breaking `vite-live-preview` explicitly does NOT support Hot Module Replacement (HMR). It is designed for full page reloads on rebuilds, not instantaneous HMR updates. ↓

fix If HMR is required, use the standard `vite dev` command instead of `vite build --watch` with `vite-live-preview`.

gotcha Vite plugins defined in your main `vite.config.ts` are NOT automatically inherited by the `vite-live-preview` server. If your preview server requires specific plugins (e.g., for asset serving or transformations), you must re-add them within the `preview` plugin's `config` option. ↓

fix Pass an object to the `config` option within the `preview()` plugin, and include the necessary plugins in its `plugins` array: `preview({ config: { plugins: [yourPlugin()] } })`.

gotcha The `vite-live-preview` server only starts when `vite build --watch` is executed. Using `vite build` (without `--watch`) or `vite dev` will not activate the preview server. ↓

fix Always use `npx vite build --watch` to ensure the preview server is launched alongside the watching build process.

gotcha When running behind a reverse proxy or in complex network environments, the WebSocket connection for automatic reloading might fail due to incorrect port mapping. The `clientPort` option addresses this. ↓

fix If the client cannot connect to the WebSocket for reloads, configure the `reload.clientPort` option to the port the client should use for the WebSocket connection, bypassing the reverse proxy's remapping if necessary. `preview({ reload: { clientPort: 80 } })`

Install

npm install vite-live-preview

yarn add vite-live-preview

pnpm add vite-live-preview

Imports

defineConfig
wrong
```
const { defineConfig } = require('vite')
```
correct
```
import { defineConfig } from 'vite'
```
Used for defining Vite configuration. Vite projects typically use ES modules; CommonJS `require` is incorrect in most modern Vite setups.
preview
wrong
```
import { preview } from 'vite-live-preview'
```
correct
```
import preview from 'vite-live-preview'
```
This is a default export. Attempting a named import will result in an undefined value or compilation error.
UserConfig
```
import type { UserConfig } from 'vite'
```
Used for type hinting when extending Vite's configuration objects, especially within the plugin's `config` option.

Quickstart

Demonstrates basic setup of the `vite-live-preview` plugin, enabling a preview server for watched Vite builds with automatic browser reloading and custom port configuration, including debug options and an example of plugin re-addition for the preview server.

import { defineConfig } from 'vite';
import preview from 'vite-live-preview';

export default defineConfig({
  // Configure the base path for your application if deployed to a sub-directory
  base: '/my-app/',
  plugins: [
    preview({
      debug: true, // Enable debug logging for the preview server
      reload: {
        enabled: true,
        delay: 1500, // Wait a bit longer after rebuilds before reloading
        // clientPort: 80, // Uncomment if behind a reverse proxy that remaps websocket ports
      },
      // If specific Vite plugins are needed for the *preview server itself*
      // (e.g., for certain asset serving or transformations), re-add them here.
      // Most build-time plugins are not necessary for previewing.
      config: {
        // plugins: [somePreviewOnlyPlugin()],
      },
    }),
  ],
  // Standard Vite preview options are inherited here
  preview: {
    port: 8080, // Configure the port for the live preview server
    strictPort: true, // Ensure the specified port is used, or exit
    open: true, // Automatically open the browser when the server starts
  },
});

// To install dependencies:
// npm install --save-dev vite vite-live-preview

// To start the build with live preview:
// npx vite build --watch