hugo-webpack-boilerplate

hugo-webpack-boilerplate is a Boilerplate that connects Hugo's static site generation to Webpack's asset pipeline, letting developers use SASS, ES6, and hashed assets in Hugo projects.

What is hugo-webpack-boilerplate?

hugo-webpack-boilerplate is an npm module that exports a preconfigured Webpack setup designed for sites built with Hugo. It takes Hugo's generated HTML and static files as input, processes them through Webpack loaders, and outputs optimized files to a dist/ folder. The project was created by Mark van Seventer and is released under the MIT License.

The core idea is that Hugo is great for static HTML but weak when you need SASS compilation, ES6 transpilation, minification, tree-shaking, or asset revving. This boilerplate hands those jobs to Webpack, giving you a conventional Hugo authoring workflow plus modern front-end optimization.

Key Features

• Zero-config Webpack configuration — Add module.exports = require('hugo-webpack-boilerplate') to your webpack.config.js; no additional loaders or plugins needed.
• Customizable output directories — Use fromConfig to set hugoPublishDir (defaults to public/) and outDir (defaults to dist/).
• SASS/SCSS support — Reference stylesheets in layouts with a tilde path like ~scss/style.scss and Webpack compiles and minifies them.
• ES6 JavaScript bundling — Script tags pointing to ~js/script.js are bundled, transpiled, and tree-shaken during the build.
• Asset revving — Output filenames include content hashes (for example style.hash.css), enabling cache busting for static assets.
• Image interpolation — The html-loader interpolation syntax ${require(...)} lets you embed images and other assets directly into Hugo templates.
• Production and development modes — Run webpack -p for a production build with minimize, or webpack -w to start the local development server with watching.
• UnCSS integration — The setup tries to remove unused CSS via UnCSS, though tilde-referenced scripts cause non-blocking error messages.

Who is it for?

• Hugo developers who want to keep Hugo's templating but also use SASS and ES6 without wiring up a separate build chain.
• Front-end developers building static sites that need minified, hashed assets for performance.
• Small teams looking for a single-command deployment workflow that combines Hugo's output and Webpack's bundle into one dist/ folder.

What can you do with it?

• Hugo theme authors: Write component styles in SCSS and have them merged, minified, and versioned into the final output.
• Static site maintainers: Run webpack -w during development to get automatic rebuilds as Hugo regenerates pages.
• Performance-focused sites: Rely on tree-shaken JavaScript and hashed filenames to reduce payload size and avoid stale caches.

How does it work?

After installing via npm install hugo-webpack-boilerplate, you require the module from your webpack.config.js. The module reads Hugo's generated site from public/ (configurable), resolves asset references using a tilde convention and html-loader interpolation, runs Webpack's pipeline, and writes the optimized site to dist/ (configurable). Currently only hugoPublishDir and outDir are configurable via fromConfig; custom loaders and plugins are not yet supported.

FAQ

I’m getting UnCSS errors, like Could not load script: "file:///~js/script.js". What does that mean?

UnCSS tries to load scripts from disk, and tilde-prefixed references don't resolve as file paths. The error is non-blocking, so the resulting stylesheet is still useful, but note that any selectors added dynamically by JavaScript will not be included in the CSS.

Why does the Webpack watcher keep reloading continuously?

There is a known bug in watchpack that causes the watcher to reload the same files repeatedly until the files settle. It's an inconvenience, but it does not affect the final bundles.

Can I add custom Webpack loaders or plugins?

No, not at this time. The fromConfig function only supports hugoPublishDir and outDir. The project's README invites users to submit an issue or pull request if they want this feature.

Is hugo-webpack-boilerplate free?

Yes, it is licensed under the MIT License, so you can use, modify, and distribute it freely, including in commercial projects.