{"id":22561,"library":"vite-hugo-plugin","title":"Vite Hugo Plugin","description":"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.","status":"active","version":"5.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/DcBD/vite-hugo-plugin","tags":["javascript","vite","plugin","hugo","typescript"],"install":[{"cmd":"npm install vite-hugo-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add vite-hugo-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-hugo-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; the plugin is designed to work with Vite and requires it to function.","package":"vite","optional":false}],"imports":[{"note":"This package is ESM-only and ships TypeScript types. Use default import. CommonJS require will fail.","wrong":"const hugoPlugin = require('vite-hugo-plugin')","symbol":"default","correct":"import hugoPlugin from 'vite-hugo-plugin'"},{"note":"The type for plugin options is named HugoPluginOptions, not Options.","wrong":"import { Options } from 'vite-hugo-plugin'","symbol":"HugoPluginOptions","correct":"import { HugoPluginOptions } from 'vite-hugo-plugin'"},{"note":"Alternative named export for the plugin function; type exported for TypeScript usage.","wrong":"","symbol":"ViteHugoPlugin","correct":"import { ViteHugoPlugin } from 'vite-hugo-plugin'"}],"quickstart":{"code":"import { resolve } from 'path';\nimport { defineConfig } from 'vite';\nimport hugoPlugin from 'vite-hugo-plugin';\n\nconst appDir = __dirname;\nconst hugoOutDir = resolve(appDir, 'public');\n\nexport default defineConfig({\n  plugins: [\n    hugoPlugin({ appDir, hugoOutDir })\n  ]\n});","lang":"typescript","description":"Basic Vite configuration integrating Hugo plugin, specifying app directory and Hugo output directory."},"warnings":[{"fix":"Upgrade Vite to 5.x or use plugin v4.x for Vite 4.x compatibility.","message":"Vite version compatibility: Plugin v5.x requires Vite >=5.0.0. Using with older Vite versions will cause type errors or runtime failures.","severity":"breaking","affected_versions":"<5.0.0"},{"fix":"Ensure Hugo is installed (brew install hugo, choco install hugo, or download from gohugo.io).","message":"Hugo must be installed separately and available in PATH. The plugin runs Hugo as a child process; missing Hugo binary will cause errors.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Remove hugoConfigFileName option; use hugo build --config myconfig.toml in your build script.","message":"The 'hugoConfigFileName' option is deprecated in favor of specifying the config file via Hugo's standard --config flag. Avoid using it in new projects.","severity":"deprecated","affected_versions":">=5.0.0"},{"fix":"Set hugoOutDir to the absolute path of Hugo's output directory (e.g., resolve(appDir, 'public')).","message":"The plugin assumes Hugo output directory is relative to appDir. If hugoOutDir is set incorrectly, Vite may not serve the generated files.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Only set ignoreHTMLFiles: true if you have other HTML files outside Hugo's output or want Vite to ignore all HTML.","message":"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.","severity":"gotcha","affected_versions":">=3.0.5"}],"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-hugo-plugin. Then use import hugoPlugin from 'vite-hugo-plugin'.","cause":"Package not installed or require() used instead of import.","error":"Error: Cannot find module 'vite-hugo-plugin'"},{"fix":"Use import hugoPlugin from 'vite-hugo-plugin' (ESM). If you must use require, do const hugoPlugin = require('vite-hugo-plugin').default.","cause":"Trying to use require() which returns an object, not the default export function.","error":"TypeError: hugoPlugin is not a function"},{"fix":"Install Hugo and verify by running 'hugo version' in your terminal.","cause":"Hugo is not installed or not in PATH.","error":"Error: The Hugo binary was not found. Make sure Hugo is installed and available in your PATH."},{"fix":"Provide correct absolute appDir path pointing to your Hugo site root.","cause":"Missing or invalid 'appDir' option, causing plugin to look for hugo.toml in wrong directory.","error":"INVALID_IDENTIFIER: Expected a valid Hugo config file. Received: undefined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}