{"id":3704,"date":"2026-11-03T23:08:45","date_gmt":"2026-11-03T15:08:45","guid":{"rendered":"http:\/\/www.asnikan.com\/blog\/?p=3704"},"modified":"2026-11-03T23:08:45","modified_gmt":"2026-11-03T15:08:45","slug":"how-do-i-use-a-pug-loader-in-webpack-4921-d4ae29","status":"publish","type":"post","link":"http:\/\/www.asnikan.com\/blog\/2026\/11\/03\/how-do-i-use-a-pug-loader-in-webpack-4921-d4ae29\/","title":{"rendered":"How do I use a pug &#8211; Loader in webpack?"},"content":{"rendered":"<p>Alright, let\u2019s cut to the chase\u2014if you\u2019ve ever stared at a messy webpack config, wondering why your pug templates aren\u2019t rendering like they\u2019re supposed, you\u2019re in the right place. I\u2019m not here to give you that generic dev tutorial that sounds like it was written by a robot who\u2019s never touched a terminal. I run a loader supply company, and let\u2019s 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\u2019ll walk you through exactly how to use it, from the basics to those little hacks that stop you from pulling your hair out. <a href=\"https:\/\/www.cnmachinery-global.com\/loader\/\">Loader<\/a><\/p>\n<p><img decoding=\"async\" src=\"https:\/\/www.cnmachinery-global.com\/uploads\/47481\/small\/telescopic-boom-excavator20d3e.jpg\"><\/p>\n<p>First off, let\u2019s get one thing straight: pug-loader doesn\u2019t work on its own. Webpack needs loaders to process different file types, and pug is just a templating language\u2014so pug-loader is the bridge between .pug files and the JavaScript that webpack can bundle. If you skip that, you\u2019ll get errors like \u201cyou may need an appropriate loader to handle this file type\u201d and trust me, that\u2019s the worst. I\u2019ve had customers call me at 2 a.m. panicking over that exact error, so let\u2019s make sure you don\u2019t become one of them.<\/p>\n<p>Let\u2019s start with the install. Yeah, I know, npm install is basic, but people mess this up all the time. You can\u2019t just do npm install pug-loader\u2014you need two things: pug (the actual template engine) and pug-loader. So run npm install pug pug-loader &#8211;save-dev. Wait, why &#8211;save-dev? Because these are tools you only use in development and build processes, not in the final bundle that runs on users\u2019 browsers. That\u2019s a quick win, don\u2019t skip the pug dependency either\u2014some people only install pug-loader and wonder why nothing works. Spoiler: the loader needs the core pug library under the hood.<\/p>\n<p>Next up, the webpack config. This is where the magic happens, and where most people go wrong. Webpack v5 is what we\u2019re 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: &#8216;pug-loader&#8217;. That\u2019s it? Wait, no\u2014if you stop here, you might run into issues if you\u2019re 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: &#8216;pug-loader&#8217; }], but wait\u2014sometimes you need options. Let\u2019s 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: &#8216;My Awesome App&#8217; } }, that way every pug template you process has access to that title variable.<\/p>\n<p>Wait, hold on\u2014there\u2019s a common gotcha here: if you\u2019re 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\u2019d have new HtmlWebpackPlugin({ template: &#8216;.\/src\/index.pug&#8217;, templateLoader: &#8216;pug-loader&#8217; }). That works, but wait\u2014some people mix this up and end up with double processing, which causes weird errors. If you\u2019re only rendering HTML, this is the way to go, but if you\u2019re importing pug templates into your JavaScript (like if you\u2019re building a component library), then you need the basic module rule I mentioned earlier.<\/p>\n<p>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\u2019t always resolve absolute paths the way you\u2019d expect. The fix here is simple: add the basedir option to pug-loader. So in your rule options, add basedir: path.resolve(__dirname, &#8216;src&#8217;), and then you can just write include components\/button.pug without the leading slash, or if you use the slash, it\u2019ll 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(&#8216;path&#8217;);, that\u2019s non-negotiable for relative paths to work.<\/p>\n<p>What about pug plugins? Let\u2019s 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\u2019d add options: { plugins: [require(&#8216;pug-plugin-for-markdown&#8217;)] }. That\u2019s way easier than I thought when I first started out\u2014no weird setup, just pass the plugin array. I\u2019ve had customers use this for things like markdown filters to add blog posts straight into their pug templates, and it works like a charm.<\/p>\n<p>Wait, let\u2019s talk about caching. Pug-loader caches templates by default, right? That\u2019s great for build speed, but if you\u2019re making changes to a pug template and nothing updates in the browser, that\u2019s why. So if you\u2019re in development mode and changes aren\u2019t showing up, add cache: false to the pug-loader options. That turns off caching, so every rebuild pulls the latest template. I know it\u2019s a tiny setting, but it saves you hours of Googling why your edits aren\u2019t working.<\/p>\n<p>Let me walk you through a real example, because theory\u2019s 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 &#8211;save-dev (add html-webpack-plugin if you need to generate HTML). Then, the webpack config:<\/p>\n<p>First, require the stuff you need: const path = require(&#8216;path&#8217;); const HtmlWebpackPlugin = require(&#8216;html-webpack-plugin&#8217;);<\/p>\n<p>Then module.exports = { entry: &#8216;.\/src\/index.js&#8217;, output: { filename: &#8216;bundle.js&#8217;, path: path.resolve(__dirname, &#8216;dist&#8217;) }, module: { rules: [ { test: \/.pug$\/, use: [ { loader: &#8216;pug-loader&#8217;, options: { basedir: path.resolve(__dirname, &#8216;src&#8217;), cache: process.env.NODE_ENV === &#8216;production&#8217; } } ] } ] }, plugins: [ new HtmlWebpackPlugin({ template: &#8216;.\/src\/index.pug&#8217; }) ] };<\/p>\n<p>Wait, see that cache line? I set cache to only be true in production, which makes sense\u2014you don\u2019t need caching slowing you down in dev, but you want it for faster builds in prod. That\u2019s a nice little optimization I learned from regulars at the loader supply shop.<\/p>\n<p>Now, test this setup. Write a simple index.pug:<\/p>\n<p>doctype html<br \/>\nhtml<br \/>\nhead<br \/>\ntitle= title<br \/>\nbody<br \/>\ninclude components\/header.pug<br \/>\np Hello from pug!<br \/>\ninclude components\/footer.pug<\/p>\n<p>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\u2019d adjust the pug-loader options to include locals: { title: &#8216;My Test App&#8217; }, and that\u2019ll show up. Alternatively, you can set it in HtmlWebpackPlugin with templateParameters, but that\u2019s another rabbit hole\u2014stick to locals for pug-specific data if you can.<\/p>\n<p>Now, let\u2019s cover common mistakes I see all the time, because that\u2019s 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\u2019re still on webpack v3, you need an older version of pug-loader (v1.x). Don\u2019t just npm install pug-loader if you\u2019re on an old webpack version\u2014check the compatibility on the package, or hit me up and I\u2019ll 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\u2019t tell you how many times a customer says \u201cpug-loader isn\u2019t working\u201d and it\u2019s because they only installed pug-loader, not pug. That\u2019s 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\u2019s why the basedir thing is so important.<\/p>\n<p>Wait, another thing: if you\u2019re 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\u2019re making changes to .pug files and they don\u2019t hot reload, make sure you have cache: false set in development, and also check that your webpack entry is set correctly so it\u2019s 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.<\/p>\n<p>Now, let\u2019s talk about advanced stuff, because once you get the basics down, you\u2019ll 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 &#8216;.\/posts.json&#8217;; Then in your webpack config\u2019s entry, wait no\u2014actually, 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(&#8216;.\/posts.json&#8217;) }, and then in your template, you can do each post in posts and render them. That\u2019s a game-changer for static sites, which are super popular with my customers.<\/p>\n<p>Also, custom pug filters. Let\u2019s say you want to write a filter that turns text into uppercase, or uses markdown. Let\u2019s say you install pug-filter-markdown, then in your options, add plugins: [require(&#8216;pug-filter-markdown&#8217;)], and then in your template you can do: :markdown # This is a heading ## This is a subheading and it\u2019ll render to proper HTML. That\u2019s so easy, and it\u2019s one of those features that makes pug-loader way better than just using plain HTML.<\/p>\n<p>Now, a quick note about when not to use pug-loader. If you\u2019re using a framework like React or Vue, you might not need to use pug-loader directly\u2014most frameworks have their own pug integrations (like vue-loader for Vue, or @pmmmwh\/react-refresh-webpack-plugin for React). But if you\u2019re 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.<\/p>\n<p>Wait, let\u2019s 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\u2014usually 2 spaces. A lot of people mix tabs and spaces, which causes those annoying \u201cunexpected indent\u201d errors. I always tell my loader customers to set their editors to use 2 spaces for .pug files, that avoids 90% of those issues.<\/p>\n<p>Okay, so you\u2019ve got your setup working, you\u2019ve 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\u2019m here to help. I supply all the loaders devs need, and I don\u2019t do that generic \u201ccheck the docs\u201d stuff\u2014my team actually troubleshoots your specific setup, whether you\u2019re on webpack v5 or a legacy v4 project. A lot of my regulars come back because I don\u2019t sell you a one-size-fits-all loader, I work with you to make sure pug fits your exact project.<\/p>\n<p>Wait, before I wrap up, let\u2019s recap the key points so you don\u2019t forget: 1. Always install both pug and pug-loader (&#8211;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.<\/p>\n<p><img decoding=\"async\" src=\"https:\/\/www.cnmachinery-global.com\/uploads\/47481\/small\/500t-all-terrain-crane-sac5000c8-8b017d.jpg\"><\/p>\n<p>If you\u2019re still struggling to get pug-loader working, or you want to customize it with additional plugins or optimizations, feel free to reach out. I\u2019m here to make sure your build setup doesn\u2019t suck, and that pug works exactly how you want it to. No hidden fees, no confusing jargon\u2014just real help for real devs.<\/p>\n<p><a href=\"https:\/\/www.cnmachinery-global.com\/gensets\/\">Gensets<\/a> \u53c2\u8003\u6587\u732e: webpack pug-loader documentation, pug templating official docs, html-webpack-plugin integration guides.<\/p>\n<hr>\n<p><a href=\"https:\/\/www.cnmachinery-global.com\/\">China Machinery International Trading Co., Ltd.<\/a><br \/>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.<br \/>Address: Room 233, 2nd Floor, Building 16A, No. 1, Shuguang Xili Jia, Chaoyang District, Beijing<br \/>E-mail: Info@tajhzg.com<br \/>WebSite: <a href=\"https:\/\/www.cnmachinery-global.com\/\">https:\/\/www.cnmachinery-global.com\/<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"<p>Alright, let\u2019s cut to the chase\u2014if you\u2019ve ever stared at a messy webpack config, wondering why &hellip; <a title=\"How do I use a pug &#8211; Loader in webpack?\" class=\"hm-read-more\" href=\"http:\/\/www.asnikan.com\/blog\/2026\/11\/03\/how-do-i-use-a-pug-loader-in-webpack-4921-d4ae29\/\"><span class=\"screen-reader-text\">How do I use a pug &#8211; Loader in webpack?<\/span>Read more<\/a><\/p>\n","protected":false},"author":390,"featured_media":3704,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[3667],"class_list":["post-3704","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-industry","tag-loader-4f2d-d4e648"],"_links":{"self":[{"href":"http:\/\/www.asnikan.com\/blog\/wp-json\/wp\/v2\/posts\/3704","targetHints":{"allow":["GET"]}}],"collection":[{"href":"http:\/\/www.asnikan.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"http:\/\/www.asnikan.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"http:\/\/www.asnikan.com\/blog\/wp-json\/wp\/v2\/users\/390"}],"replies":[{"embeddable":true,"href":"http:\/\/www.asnikan.com\/blog\/wp-json\/wp\/v2\/comments?post=3704"}],"version-history":[{"count":0,"href":"http:\/\/www.asnikan.com\/blog\/wp-json\/wp\/v2\/posts\/3704\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"http:\/\/www.asnikan.com\/blog\/wp-json\/wp\/v2\/posts\/3704"}],"wp:attachment":[{"href":"http:\/\/www.asnikan.com\/blog\/wp-json\/wp\/v2\/media?parent=3704"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"http:\/\/www.asnikan.com\/blog\/wp-json\/wp\/v2\/categories?post=3704"},{"taxonomy":"post_tag","embeddable":true,"href":"http:\/\/www.asnikan.com\/blog\/wp-json\/wp\/v2\/tags?post=3704"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}