Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
parse
✓ import parse from 'pug-parser';
✗ import { parse } from 'pug-parser';
const { parse } = require('pug-parser');
The `parse` function is the default export. CommonJS `require('pug-parser')` directly returns the function. Named import `{ parse }` or destructuring `{ parse }` for CommonJS is incorrect for this default export.
Parser
✓ import parse from 'pug-parser';
const parserInstance = new parse.Parser(tokens, options);
✗ import { Parser } from 'pug-parser';
const Parser = require('pug-parser').Parser;
The `Parser` class is exposed as a property of the default `parse` function/module, not as a direct named export. Direct usage of the `Parser` constructor is generally discouraged for typical use cases, preferring the main `parse` function.
parse (CommonJS)
✓ const parse = require('pug-parser');
✗ const { parse } = require('pug-parser');
In CommonJS environments, `require('pug-parser')` directly exports the `parse` function. Attempting to destructure it as a named export will result in `undefined`.
Demonstrates how to use `pug-lexer` to tokenize Pug source and then `pug-parser` to convert those tokens into a hierarchical Abstract Syntax Tree (AST).
const lex = require('pug-lexer');
const parse = require('pug-parser');
const filename = 'my-file.pug';
const src = 'div(data-foo="bar")\n span.text-muted Hello world';
try {
// First, lex the source to get an array of tokens
const tokens = lex(src, { filename });
// Then, parse the tokens to convert them into an AST
const ast = parse(tokens, { filename, src });
console.log('Successfully parsed Pug source to AST:');
console.log(JSON.stringify(ast, null, ' '));
// Example of accessing parts of the AST
if (ast.nodes && ast.nodes.length > 0) {
console.log(`\nRoot node type: ${ast.nodes[0].type}`);
console.log(`Root node name: ${ast.nodes[0].name}`);
}
} catch (error) {
console.error('An error occurred during parsing:', error.message);
if (error.loc) {
console.error(`Error at line ${error.loc.line}, column ${error.loc.column} in ${error.loc.filename}`);
}
}
Debug
Known issues
breakingWhen migrating from `Jade` (Pug 1.x) to `Pug` (Pug 2.x and later), significant syntax changes, deprecations, and API removals occurred across the Pug ecosystem. As `pug-parser` is a core component, these changes directly impact how Pug templates are parsed. Users should consult the Pug 2.0.0 breaking changes documentation for migration details.fixReview the official Pug 2.0.0 migration guide and update `.jade` files to `.pug` and adapt syntax according to the new specification (e.g., changes to attribute interpolation, `each` keyword usage, etc.).
affects: <2.0.0 (Jade) to >=2.0.0 (Pug)
gotchaWhile `pug-parser` itself does not directly handle compilation options like `pretty`, `templateName`, or `globals`, it is a critical component within the broader Pug compilation pipeline. Several Remote Code Execution (RCE) vulnerabilities have been identified in related `pug` packages (`pug`, `pug-code-gen`) due to improper sanitization of these options. These vulnerabilities could lead to RCE if untrusted user input directly controls such compilation options.fixAlways keep the main `pug` package and related `pug-*` dependencies updated to their latest versions to ensure all security patches are applied. Avoid passing unsanitized user input directly to compilation options like `pretty`, `templateName`, or `globals` when using `pug.compile()` or `pug.render()`.
affects: >=3.0.0 of `pug` and `pug-code-gen`, prior to latest bug fix releases
gotchaThe standalone `pug-parser` npm package has not received direct updates or new releases since version 6.0.0 (published May 2020). Although active development of parsing logic continues within the main `pugjs/pug` monorepo, direct consumers of this standalone `pug-parser` package will not receive bug fixes or feature updates without migrating to use the comprehensive `pug` package or building from the monorepo.fixFor new projects or if continuous updates are required, prefer using the main `pug` package, which bundles and manages all core components including the parser. If directly using `pug-parser`, be aware that it represents a frozen version.
affects: >=6.0.0 (standalone package)
Errors
Common errors & fixes
Error: Cannot find module 'pug-lexer'
The `pug-lexer` package, which `pug-parser` depends on for tokenizing input, is not installed in the project's dependencies.
fixInstall `pug-lexer` as a project dependency: `npm install pug-lexer`.
SyntaxError: Unexpected token ILLEGAL (or similar parsing error with line/column info)
The input Pug source string contains invalid or malformed syntax that the parser cannot interpret, or the tokens provided by `pug-lexer` were incorrect for the expected Pug grammar.
fixCarefully review the Pug template source (`src`) for any syntax errors or typos. If the error includes line and column information, use it to pinpoint the exact location of the issue. Ensure `pug-lexer` is processing valid Pug input.
TypeError: Cannot read properties of undefined (reading 'Parser') or parse.Parser is not a constructor
This error occurs when attempting to access the `Parser` class incorrectly, for instance, by assuming it's a direct named export from the module or by incorrectly destructuring a CommonJS `require()` call.
fixThe `Parser` class is exposed as a property of the default `parse` function. Access it via `new parse.Parser(tokens, options)` after correctly importing `parse` (e.g., `const parse = require('pug-parser');` for CommonJS or `import parse from 'pug-parser';` for ESM). Avoid direct named imports or `require('pug-parser').Parser`. Audit
Dependencies
pug-lexerrequiredRequired to generate the array of tokens that pug-parser consumes as its primary input.