Alright, let’s cut to the chase—if you’ve ever stared at a messy webpack config, wondering why your pug templates aren’t rendering like they’re supposed, you’re in the right place. I’m not here to give you that generic dev tutorial that sounds like it was written by a robot who’s never touched a terminal. I run a loader supply company, and let’s be real: loaders make or break your webpack setup, and pug-loader is one of the unsung heroes that most people either set up wrong or overcomplicate. I’ll walk you through exactly how to use it, from the basics to those little hacks that stop you from pulling your hair out. Loader

First off, let’s get one thing straight: pug-loader doesn’t work on its own. Webpack needs loaders to process different file types, and pug is just a templating language—so pug-loader is the bridge between .pug files and the JavaScript that webpack can bundle. If you skip that, you’ll get errors like “you may need an appropriate loader to handle this file type” and trust me, that’s the worst. I’ve had customers call me at 2 a.m. panicking over that exact error, so let’s make sure you don’t become one of them.
Let’s start with the install. Yeah, I know, npm install is basic, but people mess this up all the time. You can’t just do npm install pug-loader—you need two things: pug (the actual template engine) and pug-loader. So run npm install pug pug-loader –save-dev. Wait, why –save-dev? Because these are tools you only use in development and build processes, not in the final bundle that runs on users’ browsers. That’s a quick win, don’t skip the pug dependency either—some people only install pug-loader and wonder why nothing works. Spoiler: the loader needs the core pug library under the hood.
Next up, the webpack config. This is where the magic happens, and where most people go wrong. Webpack v5 is what we’re all using now, right? So your module.rules array is where you define how to handle .pug files. The basic rule is super simple: inside module.rules, add an object with test: /.pug$/, use: ‘pug-loader’. That’s it? Wait, no—if you stop here, you might run into issues if you’re importing other files in your pug templates, like partials or mixins. Oh right, pug has includes and extends, and if those are pointing to other files, pug-loader needs to know to process those too. So a more complete rule would be use: [{ loader: ‘pug-loader’ }], but wait—sometimes you need options. Let’s say you want to pass locals (data) to your pug templates, or disable caching, or change the file extension. The options key is your friend here. For example, if you want to pass some global data, you can add options: { locals: { title: ‘My Awesome App’ } }, that way every pug template you process has access to that title variable.
Wait, hold on—there’s a common gotcha here: if you’re using html-webpack-plugin, that changes things. A lot of people use pug with html-webpack-plugin to generate their HTML files, right? So instead of using pug-loader directly on .pug files, you might use pug-loader as a loader for html-webpack-plugin. Let me explain that. Normally, html-webpack-plugin uses ejs or other templating engines by default, so to make it use pug, you can either set the loader in the plugin config, or chain it. For example, in your plugins array, you’d have new HtmlWebpackPlugin({ template: ‘./src/index.pug’, templateLoader: ‘pug-loader’ }). That works, but wait—some people mix this up and end up with double processing, which causes weird errors. If you’re only rendering HTML, this is the way to go, but if you’re importing pug templates into your JavaScript (like if you’re building a component library), then you need the basic module rule I mentioned earlier.
Another thing: absolute paths in pug includes. Oh my god, this is the most frequent complaint I get from my loader customers. If you write include /components/button.pug in your template, pug will look relative to the current file, but pug-loader doesn’t always resolve absolute paths the way you’d expect. The fix here is simple: add the basedir option to pug-loader. So in your rule options, add basedir: path.resolve(__dirname, ‘src’), and then you can just write include components/button.pug without the leading slash, or if you use the slash, it’ll resolve correctly from the src folder. Wait, you need to import path at the top of your webpack config for that, right? So const path = require(‘path’);, that’s non-negotiable for relative paths to work.
What about pug plugins? Let’s say you want to use pug-plugin-for-something that adds custom filters or tags. Can you use that with pug-loader? Hell yeah, you just pass it to the options. For example, if you have a filter:markdown, you’d add options: { plugins: [require(‘pug-plugin-for-markdown’)] }. That’s way easier than I thought when I first started out—no weird setup, just pass the plugin array. I’ve had customers use this for things like markdown filters to add blog posts straight into their pug templates, and it works like a charm.
Wait, let’s talk about caching. Pug-loader caches templates by default, right? That’s great for build speed, but if you’re making changes to a pug template and nothing updates in the browser, that’s why. So if you’re in development mode and changes aren’t showing up, add cache: false to the pug-loader options. That turns off caching, so every rebuild pulls the latest template. I know it’s a tiny setting, but it saves you hours of Googling why your edits aren’t working.
Let me walk you through a real example, because theory’s all good, but practice is where you actually get stuff done. Suppose your project structure looks like this: src/ has index.pug, components/ has header.pug and footer.pug. Your webpack config is in the root, called webpack.config.js. First, the install: npm install pug pug-loader html-webpack-plugin –save-dev (add html-webpack-plugin if you need to generate HTML). Then, the webpack config:
First, require the stuff you need: const path = require(‘path’); const HtmlWebpackPlugin = require(‘html-webpack-plugin’);
Then module.exports = { entry: ‘./src/index.js’, output: { filename: ‘bundle.js’, path: path.resolve(__dirname, ‘dist’) }, module: { rules: [ { test: /.pug$/, use: [ { loader: ‘pug-loader’, options: { basedir: path.resolve(__dirname, ‘src’), cache: process.env.NODE_ENV === ‘production’ } } ] } ] }, plugins: [ new HtmlWebpackPlugin({ template: ‘./src/index.pug’ }) ] };
Wait, see that cache line? I set cache to only be true in production, which makes sense—you don’t need caching slowing you down in dev, but you want it for faster builds in prod. That’s a nice little optimization I learned from regulars at the loader supply shop.
Now, test this setup. Write a simple index.pug:
doctype html
html
head
title= title
body
include components/header.pug
p Hello from pug!
include components/footer.pug
Wait, where does title come from? Oh, in the pug-loader options I showed earlier, you can pass locals, or alternatively, you can pass it via HtmlWebpackPlugin. If you want to use locals there, you’d adjust the pug-loader options to include locals: { title: ‘My Test App’ }, and that’ll show up. Alternatively, you can set it in HtmlWebpackPlugin with templateParameters, but that’s another rabbit hole—stick to locals for pug-specific data if you can.
Now, let’s cover common mistakes I see all the time, because that’s what my job is: solving problems before they happen. First, using the wrong webpack version. Pug-loader v2+ works with webpack v4 and v5, but if you’re still on webpack v3, you need an older version of pug-loader (v1.x). Don’t just npm install pug-loader if you’re on an old webpack version—check the compatibility on the package, or hit me up and I’ll tell you which version to use. Second, mixing up relative and absolute paths. Like I said before, the basedir option fixes that, and I make sure all the loaders I supply have clear docs on that. Third, forgetting to import pug. I can’t tell you how many times a customer says “pug-loader isn’t working” and it’s because they only installed pug-loader, not pug. That’s the #1 mistake. Fourth, not handling partials correctly. If you have a pug template that imports another pug file, pug-loader has to process that imported file too, which it does automatically, but only if the path is right. That’s why the basedir thing is so important.
Wait, another thing: if you’re using webpack-dev-server, does that affect pug-loader? Yeah, a little. Webpack-dev-server serves files from memory, so caching might behave differently. If you’re making changes to .pug files and they don’t hot reload, make sure you have cache: false set in development, and also check that your webpack entry is set correctly so it’s watching the src folder. I always tell my customers to add watchOptions: { ignored: /node_modules/ } to their webpack config too, that keeps dev mode from being laggy.
Now, let’s talk about advanced stuff, because once you get the basics down, you’ll want to level up. What if you need to pass JavaScript data to your pug templates? Like, if you have a JSON file with blog posts, and you want to loop through them in pug. You can import the JSON in your index.js, then pass it as a local to pug-loader. For example, in src/index.js: import posts from ‘./posts.json’; Then in your webpack config’s entry, wait no—actually, you can pass locals via HtmlWebpackPlugin too, or use the pug-loader options. Wait, simpler way: in your pug-loader options, add locals: { posts: require(‘./posts.json’) }, and then in your template, you can do each post in posts and render them. That’s a game-changer for static sites, which are super popular with my customers.
Also, custom pug filters. Let’s say you want to write a filter that turns text into uppercase, or uses markdown. Let’s say you install pug-filter-markdown, then in your options, add plugins: [require(‘pug-filter-markdown’)], and then in your template you can do: :markdown # This is a heading ## This is a subheading and it’ll render to proper HTML. That’s so easy, and it’s one of those features that makes pug-loader way better than just using plain HTML.
Now, a quick note about when not to use pug-loader. If you’re using a framework like React or Vue, you might not need to use pug-loader directly—most frameworks have their own pug integrations (like vue-loader for Vue, or @pmmmwh/react-refresh-webpack-plugin for React). But if you’re building a static site, or a custom component library that uses pug templates, pug-loader is exactly what you need. I get a lot of customers who use it for internal tools, and it cuts down on their build time by so much because pug is lightweight.
Wait, let’s address a pain point I hear all the time: when pug-loader messes up indentation. Pug is all about indentation, so if your template has weird formatting, pug-loader will throw an error. The fix is simple: make sure all your files use spaces (not tabs) for indentation, and that the indentation is consistent—usually 2 spaces. A lot of people mix tabs and spaces, which causes those annoying “unexpected indent” errors. I always tell my loader customers to set their editors to use 2 spaces for .pug files, that avoids 90% of those issues.
Okay, so you’ve got your setup working, you’ve fixed all the common mistakes, now what? If you run into any issues, or if you want to optimize your pug-loader setup further, I’m here to help. I supply all the loaders devs need, and I don’t do that generic “check the docs” stuff—my team actually troubleshoots your specific setup, whether you’re on webpack v5 or a legacy v4 project. A lot of my regulars come back because I don’t sell you a one-size-fits-all loader, I work with you to make sure pug fits your exact project.
Wait, before I wrap up, let’s recap the key points so you don’t forget: 1. Always install both pug and pug-loader (–save-dev, duh). 2. Add a module rule for /.pug$/ in your webpack config, set basedir to your src folder for path fixes. 3. Turn off caching in development with cache: false. 4. If using html-webpack-plugin, set templateLoader to pug-loader. 5. Check for indentation issues and mixed tabs/spaces.

If you’re still struggling to get pug-loader working, or you want to customize it with additional plugins or optimizations, feel free to reach out. I’m here to make sure your build setup doesn’t suck, and that pug works exactly how you want it to. No hidden fees, no confusing jargon—just real help for real devs.
Gensets 参考文献: webpack pug-loader documentation, pug templating official docs, html-webpack-plugin integration guides.
China Machinery International Trading Co., Ltd.
China Machinery International Trading Co., Ltd. is one of the most experienced loader manufacturers and suppliers in China. We warmly welcome you to buy cheap loader made in China here from our factory. Quality products and reasonable price are available.
Address: Room 233, 2nd Floor, Building 16A, No. 1, Shuguang Xili Jia, Chaoyang District, Beijing
E-mail: Info@tajhzg.com
WebSite: https://www.cnmachinery-global.com/