vite-plugin-pug-transformer

1.0.8 verified Mon Apr 27 auth: no javascript

Vite plugin that transforms Pug templates into HTML using Vite's transformIndexHtml hook. Current stable version is 1.0.8. Supports Vite v2 through v7 (peer dependency: ^2.5.10 || ^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0), with Node.js version requirements aligning with Vite versions. Key differentiator: uses <template> tags with data attributes in HTML entry points rather than replacing the entire HTML, allowing multiple Pug templates per page. Ships TypeScript types. Minimal configuration with optional pugOptions and pugLocals.

Common errors

error Error: Cannot find module 'vite-plugin-pug-transformer' ↓

cause Package not installed or node_modules missing.

fix

Run npm install vite-plugin-pug-transformer or yarn add vite-plugin-pug-transformer.

error TypeError: vitePugPlugin is not a function ↓

cause Using import { vitePugPlugin } instead of default import.

fix

Use import vitePugPlugin from 'vite-plugin-pug-transformer';

error Error: [vite] Transform failed with 1 error: expected expression, got 'p' ↓

cause Using .pug file directly in JavaScript import (unsupported).

fix

Only use Pug via <template> tags in HTML; do not import .pug in JS files.

error Error: The template tag data-src is missing or invalid ↓

cause Missing or incorrect data-src attribute in <template> tag.

fix

Ensure <template data-type="pug" data-src="./yourfile.pug"> has a valid path to a .pug file.

Warnings

gotcha The plugin only transforms <template data-type="pug"> elements; standard .pug imports are NOT supported. ↓

fix Use <template data-type="pug" data-src="./file.pug"> in your HTML entry point. Do not use import .pug in JavaScript.

deprecated Support for Vite v2 and v3 is deprecated in newer versions; only Vite v4+ is actively tested. ↓

fix Upgrade to Vite v4 or newer. If you must use Vite v2/v3, pin plugin version to 1.0.6 or earlier (not verified).

gotcha Pug locals defined in pugLocals are static; dynamic values (like env variables) must be passed explicitly and will not update on hot reload. ↓

fix If you need dynamic locals, implement a custom Vite plugin that rebuilds the config on env change or use process.env inside pugOptions.

gotcha The plugin uses Vite's transformIndexHtml hook; it does not transform Pug imported in JavaScript or Vue SFCs. ↓

fix This plugin is only for the main HTML entry. For Pug in JavaScript, use another loader like @rollup/plugin-pug.

Install

npm install vite-plugin-pug-transformer

yarn add vite-plugin-pug-transformer

pnpm add vite-plugin-pug-transformer

Imports

default

wrong

const vitePugPlugin = require('vite-plugin-pug-transformer');

correct

import vitePugPlugin from 'vite-plugin-pug-transformer';

ESM-only; no default CommonJS require supported.

vitePugPlugin

wrong

import { vitePugPlugin } from 'vite-plugin-pug-transformer';

correct

import vitePugPlugin from 'vite-plugin-pug-transformer';

Default export; named import does not exist.

default with type

wrong

import * as vitePugPlugin from 'vite-plugin-pug-transformer';

correct

import vitePugPlugin from 'vite-plugin-pug-transformer';

Namespace import is not needed; use default import.

Quickstart

Shows basic setup with Vite config, HTML entry using template tags, and a simple Pug template.

// vite.config.js
import { defineConfig } from 'vite';
import vitePugPlugin from 'vite-plugin-pug-transformer';

export default defineConfig({
  plugins: [
    vitePugPlugin({
      pugLocals: { bundler: 'Vite' },
      pugOptions: { pretty: true },
    }),
  ],
});

// index.html
<!DOCTYPE html>
<html>
<body>
  <template data-type="pug" data-src="./template.pug"></template>
</body>
</html>

// template.pug
p #{bundler} is the best