vite-plugin-pug

0.4.1 verified Mon Apr 27 auth: no javascript

Vite plugin that transforms <pug> tags in HTML into compiled Pug templates. Current stable version is 0.4.1, supporting Vite 5. Releases follow no strict cadence; last update (v0.4.1) added Vite 5 support. Key differentiators: supports local variables, multiple pug tags, self-closing tags, hot reload on save, and works with both CJS and ESM. Ships TypeScript declarations. Simpler than alternatives that require Vue SFCs for Pug support.

Common errors

error Error: The service you have requested is not available yet. ↓

cause Pug template compilation failed, often due to missing pug dependency.

fix

Run npm install -D pug to add the peer dependency.

error TypeError: pugPlugin is not a function ↓

cause Named import used instead of default import.

fix

Use import pugPlugin from 'vite-plugin-pug' (no curly braces).

error [vite] Internal server error: Cannot find module 'vite-plugin-pug' ↓

cause Plugin not installed or not in node_modules.

fix

Run npm install -D vite-plugin-pug.

Warnings

deprecated Pug option `pretty` is deprecated in Pug 3 and will be removed. ↓

fix Remove `pretty` from plugin options, or use pug's built-in formatting via beautifier.

breaking v0.3.0 changed to only accept `options` (pug options) and `locals` (data) as separate parameters, rather than a single object. ↓

fix Update config: `pugPlugin(options, locals)` instead of `pugPlugin({locals, ...})`.

gotcha Local imports (`localImports` option) only work when the pug `src` attribute is a relative path. Does not support absolute paths or module resolution. ↓

fix Ensure all pug src paths are relative to the importing HTML file.

Install

npm install vite-plugin-pug

yarn add vite-plugin-pug

pnpm add vite-plugin-pug

Imports

default (pugPlugin)
wrong
```
const pugPlugin = require('vite-plugin-pug')
```
correct
```
import pugPlugin from 'vite-plugin-pug'
```
ESM-only; CJS require works but not recommended since v0.3.1 ships ESM only.
default (pugPlugin)
wrong
```
import { pugPlugin } from 'vite-plugin-pug'
```
correct
```
import pugPlugin from 'vite-plugin-pug'
```
The package exports a default function, not a named export.
Type (PluginOptions)
```
import type { PluginOptions } from 'vite-plugin-pug'
```
TypeScript users can import the PluginOptions type for better intellisense.

Quickstart

Configures Vite to use vite-plugin-pug with Pug pretty-printing option and local variables.

// vite.config.ts
import { defineConfig } from 'vite'
import pugPlugin from 'vite-plugin-pug'

const options = { pretty: true, basedir: process.cwd() }
const locals = { name: 'World' }

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