Vite Hugo Plugin

5.1.0 verified Mon Apr 27 auth: no javascript

A Vite plugin that integrates the Hugo static site generator into a Vite build pipeline, enabling seamless development and bundling of Hugo sites with Vite's HMR, CSS/JS processing, and asset handling. Current version 5.1.0 supports Vite 5.x and Hugo, shipping TypeScript types. Key differentiators: automatic Hugo rebuild on changes, configurable Hugo output directory and config file name, and optional ignoring of Hugo-generated HTML files to avoid conflicts with Vite's HTML handling. Maintained actively with regular updates.

Common errors

error Error: Cannot find module 'vite-hugo-plugin' ↓

cause Package not installed or require() used instead of import.

fix

Install the package: npm install vite-hugo-plugin. Then use import hugoPlugin from 'vite-hugo-plugin'.

error TypeError: hugoPlugin is not a function ↓

cause Trying to use require() which returns an object, not the default export function.

fix

Use import hugoPlugin from 'vite-hugo-plugin' (ESM). If you must use require, do const hugoPlugin = require('vite-hugo-plugin').default.

error Error: The Hugo binary was not found. Make sure Hugo is installed and available in your PATH. ↓

cause Hugo is not installed or not in PATH.

fix

Install Hugo and verify by running 'hugo version' in your terminal.

error INVALID_IDENTIFIER: Expected a valid Hugo config file. Received: undefined ↓

cause Missing or invalid 'appDir' option, causing plugin to look for hugo.toml in wrong directory.

fix

Provide correct absolute appDir path pointing to your Hugo site root.

Warnings

breaking Vite version compatibility: Plugin v5.x requires Vite >=5.0.0. Using with older Vite versions will cause type errors or runtime failures. ↓

fix Upgrade Vite to 5.x or use plugin v4.x for Vite 4.x compatibility.

gotcha Hugo must be installed separately and available in PATH. The plugin runs Hugo as a child process; missing Hugo binary will cause errors. ↓

fix Ensure Hugo is installed (brew install hugo, choco install hugo, or download from gohugo.io).

deprecated The 'hugoConfigFileName' option is deprecated in favor of specifying the config file via Hugo's standard --config flag. Avoid using it in new projects. ↓

fix Remove hugoConfigFileName option; use hugo build --config myconfig.toml in your build script.

gotcha The plugin assumes Hugo output directory is relative to appDir. If hugoOutDir is set incorrectly, Vite may not serve the generated files. ↓

fix Set hugoOutDir to the absolute path of Hugo's output directory (e.g., resolve(appDir, 'public')).

gotcha When using 'ignoreHTMLFiles' option, Hugo-generated HTML files are ignored by Vite. This may break Vite's HTML processing for pages you want Vite to handle. ↓

fix Only set ignoreHTMLFiles: true if you have other HTML files outside Hugo's output or want Vite to ignore all HTML.

Install

npm install vite-hugo-plugin

yarn add vite-hugo-plugin

pnpm add vite-hugo-plugin

Imports

default
wrong
```
const hugoPlugin = require('vite-hugo-plugin')
```
correct
```
import hugoPlugin from 'vite-hugo-plugin'
```
This package is ESM-only and ships TypeScript types. Use default import. CommonJS require will fail.

HugoPluginOptions

wrong

import { Options } from 'vite-hugo-plugin'

correct

import { HugoPluginOptions } from 'vite-hugo-plugin'

The type for plugin options is named HugoPluginOptions, not Options.

ViteHugoPlugin
```
import { ViteHugoPlugin } from 'vite-hugo-plugin'
```
Alternative named export for the plugin function; type exported for TypeScript usage.

Quickstart

Basic Vite configuration integrating Hugo plugin, specifying app directory and Hugo output directory.

import { resolve } from 'path';
import { defineConfig } from 'vite';
import hugoPlugin from 'vite-hugo-plugin';

const appDir = __dirname;
const hugoOutDir = resolve(appDir, 'public');

export default defineConfig({
  plugins: [
    hugoPlugin({ appDir, hugoOutDir })
  ]
});