Pug with Vite

Vite is a front-end build tool and development server: it refreshes the page in the browser after an edit and builds the files for publishing. Vite does not understand Pug, but you can teach it with a plugin — an add-on enabled in the Vite config. If the script from the previous lesson is enough for you, you can skip this lesson.

The plugin

There is no official Pug plugin for Vite. This lesson uses the third-party package vite-plugin-pug-transformer: it inserts the HTML rendered from a Pug template into the index.html page. At the time of writing the plugin supports Vite up to version 7, so set the Vite version explicitly:

mkdir cafe-vite
cd cafe-vite
npm init -y
npm pkg set type=module
npm install --save-dev vite@7 vite-plugin-pug-transformer

Before installing, check the plugin page on npmjs.com: if a version supporting a newer Vite is out, you can drop the @7.

Configuration

Create the file vite.config.js in the project root:

// vite.config.js
import { defineConfig } from "vite";
import pugPlugin from "vite-plugin-pug-transformer";
 
export default defineConfig({
  plugins: [pugPlugin()],
});

The plugins array lists the plugins Vite runs while processing files.

The page and the template

Vite starts from the index.html file in the project root. Create it and mark the place for the template with a template tag:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Morning Café</title>
  </head>
  <body>
    <template data-type="pug" data-src="./src/index.pug"></template>
  </body>
</html>

In the browser this file is empty for now: the template tag shows nothing. The data-src attribute is the path to the template. Create the file src/index.pug:

h1 Morning Café
p Fresh coffee every day from 8:00.

Running it

npx vite

Open http://localhost:5173 and you will see the heading and the paragraph. Change the text in src/index.pug and save the file: Vite reloads the page by itself.

The command npx vite build builds the files for publishing. In dist/index.html the template tag is replaced with the template result:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Morning Café</title>
  </head>
  <body>
    <h1>Morning Café</h1><p>Fresh coffee every day from 8:00.</p>
  </body>
</html>

The plugin does not turn on pretty, so the tags from the template are on one line. Pug options are passed to the plugin with the pugOptions parameter, and data for the template with pugLocals.

Script or Vite

The rest of the course uses the script: it is simpler and shows clearly how Pug works.

Common mistake

Writing Pug markup right inside the template tag in index.html. The plugin reads the template only from the file named in data-src, so keep Pug code in .pug files.