Open-source project
pugjs/pug avatar
pugjs/pug

Pug's twelve-package pipeline, three documented options, and the gap between 3.0.3 and 3.0.4

Pug – robust, elegant, feature rich template engine for Node.js

21,818 stars1,931 forksJavaScriptLicense varies

At a glance

What is it?
Pug compiles whitespace-sensitive templates to HTML for Node.js and, with one flag, to JavaScript for the browser. It ships as twelve packages from one private monorepo, documents three options, and its newest tag is dated 2026-03-13 after a gap of nearly two years.
Who is it for?
Pug is a reasonable pick for a Node project that wants terse templates, a compile step it controls, and a runtime package it can ship without the compiler. It is a poor fit if you need a browser build without a bundler step, or if you want a parser that tracks new Node releases quickly: the last push is dated 2026-03-13 and the preceding release is dated 2024-05-24.
Can I use it commercially?
Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
Is it still maintained?
Activity is slowing. The repository last received commits 8 months ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • pugjs/pug21,818 ★ · -25
Star history
Repository2026-09-212026-11-15
pugjs/pug21.8k21.8k

-25 Stars in the last 55 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

v3.0.3 sat for almost two years before v3.0.4 landed

The release list shows [email protected] on 2024-05-24, then [email protected] and [email protected] on 2026-03-13, and the repository's last push carries that same 2026-03-13 timestamp. That is the state of the project today, and it is not a fast-moving one. Nearly two years separate the two most recent tags. Two consequences for a team choosing a template engine. A dependency audit that expects a parser to track new Node releases finds nothing recent here to check against. And the project itself says the website and documentation are still being updated, so a syntax question may resolve against pugjs.org rather than against the source in this repository. Nothing in the metadata marks the project archived, but a repository whose newest tag is from March 2026 is not where you look for a monthly answer to a compiler bug.

One npm install pulls a package out of a twelve-package monorepo

The consumer side of Pug is one line:

bash
$ npm install pug

Behind it sits a pipeline of twelve packages named in the version table: pug, pug-attrs, pug-code-gen, pug-error, pug-filters, pug-lexer, pug-linker, pug-load, pug-parser, pug-runtime, pug-strip-comments, and pug-walk. The root package.json is private, declares packages/* as its workspaces, and carries a rollingversions ignore flag, so those twelve are built together and published separately. That table is wrapped in a VERSION_TABLE comment and lists each package with an npm link. The practical consequence is that a bug in the lexer or the linker is fixed by a release of a different package than pug, so watching the pug version alone does not tell you whether your parse step changed. It also means a consumer who wants the runtime without the compiler reaches for pug-runtime directly, and pug-walk ships as its own package too, so the word pug in your lockfile is not a statement about which parts of the pipeline you have.

filename is not optional on any render path that uses includes

Only three options are written down: filename, used in exceptions and required when using includes; compileDebug, where false means no debug instrumentation is compiled; and pretty, which adds pretty-indentation whitespace to output and is false by default. Each one removes something quietly. A template that pulls in a partial with no filename set has nothing to resolve the include against, and the failure text for that case is not spelled out. Turning compileDebug to false means no debug instrumentation is compiled. Leaving pretty off, which is the default, means no pretty-indentation whitespace is added to the output. The rest of the API is delegated to pugjs.org/api/reference.html, and the summary here is three calls:

js
var pug = require('pug');

// compile
var fn = pug.compile('string of pug', options);
var html = fn(locals);

// render
var html = pug.render('string of pug', merge(options, locals));

// renderFile
var html = pug.renderFile('filename.pug', merge(options, locals));

Note that the snippet calls merge(options, locals) in two of the three calls without showing where merge comes from, so copying it into a fresh file fails until you supply that helper yourself.

The browser path is a build step, because the standalone file is a large one

Browser support comes with two warnings attached: the latest version can be downloaded in standalone form from pugjs.org/js/pug.js, that build only supports the very latest browsers and is a large file, and the recommendation is to pre-compile your templates to JavaScript. The command does the second thing:

bash
$ pug --client --no-debug filename.pug

which produces filename.js containing the compiled template. Read the flags rather than skip them. --no-debug drops the debug instrumentation on the client side, matching the compileDebug option on the server side, so a client bundle and a server render configured the same way stay consistent. The real consequence is that filename.js becomes a build artifact, so a template edit needs a rebuild step in your pipeline instead of a runtime compile, and that artifact is the only client path the project actually recommends. Nothing states a supported browser list or a polyfill story, so if you have to serve anything older than current browsers the project gives you no answer and you are choosing a different approach. The two routes are also not equivalent in behaviour: one evaluates template text in the page, the other ships a compiled function.

The Jade rename kept the old package name and moved the syntax notes to issue 2305

Pug was formerly known as Jade, and the reason is legal rather than aesthetic: Jade turned out to be a registered trademark, so a rename was needed and Pug was chosen after discussion among the maintainers. As of version 2, pug is the official package name. The old name was not released into oblivion, because the maintainers secured permission to keep occupying the jade package name, so an application can still resolve jade while every new version ships under pug. The rename landed on top of work that was already called Jade 2.0.0, which is why it coincided with the major version bump and why upgrading reads as an ordinary major-version upgrade. That framing hides the real cost. The syntax of Pug has several differences, deprecations, and removals compared to Jade, and those are collected in issue 2305 rather than in a migration guide here. Templates written against old Jade will not simply render after the package swap, and an error you see after upgrading may be one of the removals rather than an API you misused.

The repository builds with yarn workspaces while the install docs use npm

What a contributor runs and what a user runs are different setups. The root package.json is a private workspace root pinned to yarn, with a yarn.lock at the top level and no npm lockfile, and its build script chains three things: node scripts/prebuild, then wsrun --stages --exclude-missing --fast-exit --collect-logs build, then tsc --build scripts. pretest runs yarn build before jest, and watch is jest --watch. Jest is configured with testEnvironment node and three snapshot serializers kept in scripts, one for filenames, one for prettier output, one for buffers. The toolchain versions explain why the test harness looks dated: jest is pinned at ^26.0.1, prettier is pinned exactly at 1.19.1, typescript at ^4.1.2, wsrun at ^5.2.0, coveralls at 3.0.9. So if you clone this repository expecting the npm install pug path to also give you a way to verify a change, it does not. The consumer instructions and the contributor instructions are two different projects that share a directory.

Framework adapters and ports are links, not versions this repository controls

A long tail of integrations is listed by URL alone. Close-syntax ports exist for PHP, Java as jade4j, Python as pypugjs, Ruby as pug-ruby, C# on ASP.NET Core as pugzor, and RPG/ILE as apug. Different-syntax equivalents with the same philosophy are Scaml for Scala, Slim for Ruby, and Haml for Ruby. Embedded adapters cover Laravel, Symfony, Phalcon, CodeIgniter, Yii 2, Slim 3, a Silex example, Lumen, and Rails, and the CMS plugin listed is wordless for WordPress. What the list does not carry is any version constraint. Nothing here says which pug major each adapter targets, and nothing says which pug major was current when the adapter last changed. That is the practical trap: upgrading pug inside your application and upgrading the adapter that renders your views are separate upgrades living in separate repositories, and a mismatch shows up as a template error long after the upgrade rather than at install time. Bug reports and feature requests for the engine itself are asked for in the pugjs/pug issue tracker, which is a reminder that a port's problems belong in the port's own tracker.

Editorial conclusion

Pug is a reasonable pick for a Node project that wants terse templates, a compile step it controls, and a runtime package it can ship without the compiler. It is a poor fit if you need a browser build without a bundler step, or if you want a parser that tracks new Node releases quickly: the last push is dated 2026-03-13 and the preceding release is dated 2024-05-24. Before committing, set filename on every render path that uses includes, decide whether compileDebug stays on in production, and check which framework adapter you intend to use against your pug major, because those adapters live in other repositories and are not pinned here.

Frequently asked questions

Why use Pug instead of HTML?

Pug gives you a whitespace-sensitive syntax that compiles to plain HTML, so the same template can also compile to JavaScript for the browser with a command line flag. Its shorthand is visible in the documented example, where #container.col becomes <div id="container" class="col"> and title= pageTitle interpolates a variable.

What does Pug stand for?

The project does not give an expansion. Pug is the name chosen after discussion among the maintainers to replace Jade, which had to be renamed because Jade is a registered trademark, and as of version 2 pug is the official npm package name.

Are there two types of Pugs?

This repository is about Pug the template engine, heavily influenced by Haml and implemented with JavaScript for Node.js and browsers. Its scope, options and API are the ones described at pugjs.org.

What is Pug in French?

This repository documents a JavaScript template engine for Node.js and browsers, renamed from Jade, published as twelve npm packages from one monorepo and documented at pugjs.org.

Official sources

  1. Issues
  2. Project website
  3. pugjs/pug on GitHub
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/pugjs-pug.svg)](https://hysenlabs.com/projects/pugjs-pug)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/pugjs-pug.svg)](https://hysenlabs.com/projects/pugjs-pug)

Was this useful?