Using Pug.js with Vue.js

Installation and Setup Requirements

To use Pug with Vue.js, you'll need to install the necessary packages and configure your build tool. The setup process varies slightly depending on whether you're using Vue CLI, Vite, or a custom webpack configuration, but the core dependencies remain consistent.

Required Packages

The essential packages for using Pug with Vue include the main pug package and a loader for your build tool. For webpack-based projects (including Vue CLI), you'll need pug-plain-loader to process Pug templates within Vue components. Vite users can use the vite-plugin-pug or configure the built-in preprocessing support.

# For webpack/Vue CLI projects
npm install pug pug-plain-loader --save-dev

# For Vite projects
npm install pug --save-dev
npm install vite-plugin-pug --save-dev

Vue CLI Configuration

When using Vue CLI, configure the loader to properly process Pug files by modifying the vue.config.js file. This ensures that pug-plain-loader processes .vue files with lang="pug" attributes correctly, allowing Vue's template compiler to handle the Pug syntax before compilation.

// vue.config.js
module.exports = {
 chainWebpack: config => {
 config.module
 .rule('pug')
 .test(/\.pug$/)
 .use('pug-plain-loader')
 .loader('pug-plain-loader')
 .end()
 }
}

Vite Configuration

For Vite-based projects, add the Pug plugin to your vite.config.js. The plugin handles automatic preprocessing of Pug templates within Vue Single File Components:

// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import pugPlugin from 'vite-plugin-pug'

export default defineConfig({
 plugins: [
 vue(),
 pugPlugin()
 ]
})

With either configuration in place, you can immediately begin using lang="pug" in your Vue component templates. The build tool will automatically detect the attribute and process the template through the appropriate Pug loader or plugin.

Writing Vue Templates with Pug Syntax

Once configured, you can use Pug syntax within Vue Single File Components by adding lang="pug" to the template tag. This tells the build tool to process the template content as Pug before compilation. The Pug syntax integrates seamlessly with Vue's directives, allowing you to use v-if, v-for, :bind, @click, and other Vue-specific attributes directly.

Basic Template Comparison

Understanding the differences between HTML and Pug syntax helps developers transition smoothly. The following comparison illustrates how the same Vue component structure appears in both syntaxes:

// Pug syntax
template(lang="pug")
 .user-card-component
 .user-card-component__avatar
 img(:src='avatar' class='user-card-component__avatar-image')
 
 .user-card-component__name {{ username }}
 
 .user-card-component__email {{ email }}
 
 .user-card-component__action
 button(@click="$emit('contactUser')") Contact {{ lastName }}

This Pug template compiles to standard HTML that Vue can process, maintaining all reactivity and directive functionality. The indentation defines the DOM hierarchy, while the dot notation creates class attributes automatically.

Working with Vue Directives in Pug

Vue directives translate naturally to Pug syntax. The v-bind directive uses a colon prefix (:src for v-bind:src), while v-on uses the @ prefix (@click for v-on:click). Conditionals like v-if and loops like v-for work identically to their HTML counterparts.

template(lang="pug")
 div
 // Conditional rendering
 p(v-if="isVisible") Content is visible
 
 // List rendering with v-for
 ul(v-for="item in items" :key="item.id")
 li {{ item.name }}
 
 // Event handling
 button(@click="handleClick") Click Me
 
 // Attribute binding
 img(:src="imageUrl" :alt="imageAlt")

The Pug compiler handles the translation to standard Vue template syntax automatically, so all Vue reactivity features work as expected.

Using Mixins and Includes

Pug's mixin feature proves particularly valuable when building reusable Vue components. Mixins allow you to define reusable template fragments that can be included across multiple components, reducing code duplication and maintaining consistency:

// Defining a mixin
mixin button-primary(content, clickHandler)
 button.btn-primary(@click="clickHandler") {{ content }}

// Using the mixin
+button-primary('Submit', handleSubmit)
+button-primary('Cancel', handleCancel)

This approach works well for UI patterns that appear frequently within an application, such as form buttons, card layouts, or modal structures. By centralizing these patterns in mixin definitions, you ensure visual and functional consistency across components while reducing the maintenance burden of duplicated code.

Best Practices for Pug With Vue

Following established best practices ensures that your Pug templates remain maintainable and performant. These guidelines help teams adopt Pug effectively while avoiding common pitfalls.

Consistent Indentation

Maintain consistent indentation (typically two spaces) throughout your Pug templates. Since Pug relies on indentation to define structure, inconsistent spacing can lead to compilation errors or incorrect HTML output. Establish team-wide standards and consider configuring your editor to use space-based indentation for Pug files. Most modern editors including VS Code (with Pug extension), WebStorm, and Vim support Pug syntax highlighting and formatting.

Component Organization

Structure complex templates using Pug's block and mixin features to maintain readability. Large templates benefit from breaking into smaller, named blocks that can be visually distinguished within the file. This organization makes it easier to locate and modify specific sections of template code. Consider extracting frequently-used patterns into separate mixin files that can be imported across components.

Debugging Strategies

Modern IDEs and editors provide syntax highlighting and error detection for Pug files when properly configured. Setting up your development environment to highlight Pug syntax improves code readability and helps catch syntax errors early in the development process. Browser DevTools can still inspect the rendered HTML, making debugging straightforward regardless of the template syntax used.

When debugging, remember that Pug compiles to standard HTML. Any runtime issues you encounter in the browser will show the same HTML structure you would see from a traditional HTML template. This means existing Vue debugging techniques--including Vue DevTools, component inspection, and reactive state tracing--work identically with Pug templates.

Team Adoption Tips

For teams new to Pug, consider a gradual adoption strategy. Start by using Pug only in new components, allowing team members to build familiarity without the pressure of migrating existing code. Establish a shared mixin library for common patterns early in the adoption process, as this demonstrates immediate value and reduces repetitive code across components.

Document team conventions for Pug usage, including indentation standards, mixin naming conventions, and when to use Pug versus plain HTML. This documentation serves as onboarding material for new team members and ensures consistency as the codebase grows. Following these practices as part of your overall /services/web-development/ workflow leads to more maintainable and scalable Vue applications.

Common Patterns and Examples

Several common patterns emerge when using Pug with Vue components. Understanding these patterns helps developers write more effective templates and leverage Pug's strengths.

Forms with Validation

Building forms with Pug simplifies the structure while maintaining access to all Vue form handling features. The concise syntax makes form layouts easier to read and modify:

template(lang="pug")
 form(@submit.prevent="submitForm")
 .form-group
 label(for="email") Email
 input(
 v-model="email"
 type="email"
 id="email"
 :class="{ 'is-invalid': errors.email }"
 )
 span.error(v-if="errors.email") {{ errors.email }}
 
 .form-group
 label(for="password") Password
 input(
 v-model="password"
 type="password"
 id="password"
 )
 
 button(type="submit") Submit

Conditional Class Bindings

Pug handles Vue's class binding syntax elegantly, allowing complex conditional classes without verbose HTML attributes:

template(lang="pug")
 .task-item(
 :class="{ 'is-complete': task.done, 'is-priority': task.priority }"
 )
 .task-title {{ task.title }}
 .task-status(v-if="task.done") Completed

This pattern keeps template code clean while supporting sophisticated conditional styling.

Modal Components

Modals benefit significantly from Pug's concise structure, with clear separation between overlay, container, and content:

template(lang="pug")
 .modal-overlay(v-if="isOpen" @click.self="$emit('close')")
 .modal-container
 .modal-header
 h3 {{ title }}
 button.close(@click="$emit('close')") ×
 
 .modal-body
 slot
 
 .modal-footer
 button(@click="$emit('cancel')") Cancel
 button.primary(@click="$emit('confirm')") Confirm

Navigation Menus

Navigation structures with dynamic items render cleanly in Pug:

template(lang="pug")
 nav.main-navigation
 .logo
 img(:src="logoUrl" :alt="logoAlt")
 
 ul.nav-links
 li.nav-item(v-for="item in menuItems" :key="item.id")
 a(:href="item.url" :class="{ 'active': item.active }")
 | {{ item.label }}

Card Component Layouts

Card-based layouts showcase Pug's ability to represent nested structures efficiently:

template(lang="pug")
 .card-grid
 .card(v-for="product in products" :key="product.id")
 .card-image
 img(:src="product.image" :alt="product.name")
 
 .card-content
 h3.card-title {{ product.name }}
 p.card-description {{ product.description }}
 
 .card-footer
 span.price {{ product.price }}
 button.add-to-cart(@click="addToCart(product)")
 | Add to Cart

Conclusion

Using Pug with Vue.js Single File Components offers a compelling alternative to traditional HTML templates. The cleaner syntax, reduced boilerplate, and natural integration with Vue's directive system make it an excellent choice for teams looking to improve template maintainability. With straightforward setup through Vue CLI or Vite and full support for all Vue features, adopting Pug requires minimal overhead while providing meaningful productivity benefits.

Key Takeaways:

• Setup is straightforward with Vue CLI or Vite--install the appropriate loader and add lang="pug" to your template tags
• All Vue features work seamlessly with Pug syntax, including directives, slots, and reactivity
• Consistent indentation is critical for maintainability--establish team standards early
• Mixins and includes promote code reuse and consistency across components
• Performance impact is negligible with modern tooling--the compiled bundle size remains identical

The key to success lies in establishing team standards, maintaining consistent formatting, and leveraging Pug's features (mixins, includes, blocks) strategically. For projects with complex template requirements or teams familiar with templating engines, Pug provides a productive path to writing cleaner Vue components.

If you're building Vue applications and currently struggling with verbose HTML templates, giving Pug a try can refresh your development experience. Start with a new component, establish your team's conventions, and expand adoption as comfort grows. The initial learning curve pays dividends in reduced syntax errors, cleaner code reviews, and more maintainable templates over time. Partnering with an experienced /services/web-development/ team can help you implement these best practices effectively across your Vue.js projects.

Sources

1. Devjavu - Building Vue Components With Pug & Stylus - Comprehensive guide on building Vue components with Pug and Stylus
2. LogRocket - Using Pug.js with Vue.js - Tutorial covering integration of Vue.js with Pug as a templating engine
3. Vue.js Official Documentation - Template Syntax - Official Vue.js template syntax documentation
4. Pug.js Official Documentation - Official Pug documentation for template syntax and features
5. Vue.js Single File Components - Vue SFC documentation showing template preprocessor support