0
# Pug
1
2
Pug is a high-performance template engine for Node.js and browsers that transforms clean, whitespace-sensitive syntax into HTML. It provides a concise and intuitive way to write HTML templates using indentation-based structure, element classes and IDs via CSS selector syntax, JavaScript expressions for dynamic content, conditionals and loops for logic, mixins for reusable components, and includes/extends for template composition.
3
4
## Package Information
5
6
- **Package Name**: pug
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install pug`
10
11
## Core Imports
12
13
```javascript
14
const pug = require("pug");
15
```
16
17
For ES modules:
18
19
```javascript
20
import pug from "pug";
21
```
22
23
## Basic Usage
24
25
```javascript
26
const pug = require("pug");
27
28
// Compile a template from string
29
const template = pug.compile('p Hello #{name}!');
30
const html = template({ name: 'World' });
31
// Result: <p>Hello World!</p>
32
33
// Render directly from string
34
const html2 = pug.render('h1 Welcome to #{site}', { site: 'Pug' });
35
// Result: <h1>Welcome to Pug</h1>
36
37
// Render from file
38
const html3 = pug.renderFile('template.pug', { user: 'Alice' });
39
```
40
41
## Architecture
42
43
Pug is built around several key components:
44
45
- **Compilation API**: Functions to compile templates into reusable functions (`compile`, `compileFile`)
46
- **Rendering API**: Direct template-to-HTML conversion (`render`, `renderFile`)
47
- **Client-Side Compilation**: Generate JavaScript code for browser use (`compileClient`, `compileFileClient`)
48
- **Template Caching**: Built-in caching system for improved performance
49
- **Plugin System**: Extensible architecture supporting custom processing stages
50
- **Express Integration**: Native support for Express.js view engine
51
52
## Capabilities
53
54
### Template Compilation
55
56
Core compilation functionality for transforming Pug templates into executable JavaScript functions. Essential for production applications requiring maximum performance.
57
58
```javascript { .api }
59
/**
60
* Compile a Pug template string into a function
61
* @param str - Pug template source code
62
* @param options - Compilation options
63
* @returns Template function that accepts locals and returns HTML string
64
*/
65
function compile(str, options);
66
67
/**
68
* Compile a Pug template file into a function
69
* @param path - Path to Pug template file
70
* @param options - Compilation options
71
* @returns Template function with caching support
72
*/
73
function compileFile(path, options);
74
```
75
76
[Template Compilation](./compilation.md)
77
78
### Template Rendering
79
80
Direct template-to-HTML conversion for simple use cases and development environments. Combines compilation and execution in a single step.
81
82
```javascript { .api }
83
/**
84
* Render a Pug template string directly to HTML
85
* @param str - Pug template source code
86
* @param options - Rendering options including locals
87
* @param fn - Optional callback for async operation
88
* @returns HTML string (sync) or calls callback (async)
89
*/
90
function render(str, options, fn);
91
92
/**
93
* Render a Pug template file directly to HTML
94
* @param path - Path to Pug template file
95
* @param options - Rendering options including locals
96
* @param fn - Optional callback for async operation
97
* @returns HTML string (sync) or calls callback (async)
98
*/
99
function renderFile(path, options, fn);
100
```
101
102
[Template Rendering](./rendering.md)
103
104
### Client-Side Compilation
105
106
Browser-compatible template compilation for client-side rendering. Generates standalone JavaScript code that can run without Node.js dependencies.
107
108
```javascript { .api }
109
/**
110
* Compile template to JavaScript source for browser use
111
* @param str - Pug template source code
112
* @param options - Client compilation options
113
* @returns JavaScript source code string
114
*/
115
function compileClient(str, options);
116
117
/**
118
* Compile template file to client-side JavaScript
119
* @param path - Path to Pug template file
120
* @param options - Client compilation options
121
* @returns JavaScript source code string with caching
122
*/
123
function compileFileClient(path, options);
124
125
/**
126
* Compile template with dependency tracking
127
* @param str - Pug template source code
128
* @param options - Compilation options
129
* @returns Object with body (JavaScript code) and dependencies array
130
*/
131
function compileClientWithDependenciesTracked(str, options);
132
```
133
134
[Client-Side Compilation](./client-compilation.md)
135
136
### Configuration and Caching
137
138
Template caching, global filters, and runtime configuration for optimizing performance and extending functionality.
139
140
```javascript { .api }
141
/**
142
* Template function cache for compiled templates
143
*/
144
const cache;
145
146
/**
147
* Global custom filters registry
148
*/
149
const filters;
150
151
/**
152
* Pug runtime helpers for template execution
153
*/
154
const runtime;
155
156
/**
157
* Library identification name
158
*/
159
const name;
160
```
161
162
[Configuration and Caching](./configuration.md)
163
164
### Express.js Integration
165
166
Native Express.js view engine support for seamless web application integration.
167
168
```javascript { .api }
169
/**
170
* Express.js view engine interface
171
* @param path - Template file path
172
* @param options - View options from Express
173
* @param fn - Express callback function
174
*/
175
function __express(path, options, fn);
176
```
177
178
[Express Integration](./express-integration.md)
179
180
### Node.js require() Registration
181
182
Direct .pug file support through Node.js require() system for seamless template loading in applications.
183
184
```javascript { .api }
185
/**
186
* Register .pug extension with Node.js require() system
187
*/
188
require('pug/register');
189
```
190
191
[Configuration and Caching](./configuration.md)
192
193
## Common Options
194
195
Most functions accept an options object with these common properties:
196
197
```javascript { .api }
198
interface PugOptions {
199
/** Used for error reporting and resolving includes/extends */
200
filename?: string;
201
/** Include debugging information (default: true in development) */
202
compileDebug?: boolean;
203
/** Add pretty-indentation to output (default: false) */
204
pretty?: boolean;
205
/** Base directory for resolving includes and extends */
206
basedir?: string;
207
/** Set default doctype if not specified in template */
208
doctype?: string;
209
/** Custom filters for template processing */
210
filters?: { [name: string]: Function };
211
/** Options passed to filters */
212
filterOptions?: any;
213
/** Aliases for filter names */
214
filterAliases?: { [alias: string]: string };
215
/** Variables to make available globally in templates */
216
globals?: string[];
217
/** Use self namespace for locals (default: false) */
218
self?: boolean;
219
/** Enable template caching (requires filename) */
220
cache?: boolean;
221
/** Inline runtime functions in generated code */
222
inlineRuntimeFunctions?: boolean;
223
/** Array of compilation plugins */
224
plugins?: PugPlugin[];
225
/** Include source maps in debug builds */
226
includeSources?: boolean;
227
/** Name for the generated template function */
228
templateName?: string;
229
/** Debug compilation process */
230
debug?: boolean;
231
}
232
```
233
234
## Types
235
236
```javascript { .api }
237
/**
238
* Compiled template function
239
*/
240
type TemplateFunction = (locals?: any) => string;
241
242
/**
243
* Plugin interface for extending Pug compilation
244
*/
245
interface PugPlugin {
246
/** Hook into lexical analysis stage */
247
lex?: Function;
248
/** Hook into parsing stage */
249
parse?: Function;
250
/** Custom file resolution */
251
resolve?: Function;
252
/** Custom file reading */
253
read?: Function;
254
/** Custom code generation */
255
generateCode?: Function;
256
/** Pre-processing hooks */
257
preLex?: Function;
258
postLex?: Function;
259
preParse?: Function;
260
postParse?: Function;
261
preLoad?: Function;
262
postLoad?: Function;
263
preFilters?: Function;
264
postFilters?: Function;
265
preLink?: Function;
266
postLink?: Function;
267
preCodeGen?: Function;
268
postCodeGen?: Function;
269
}
270
271
/**
272
* Compilation result with dependency tracking
273
*/
274
interface CompilationResult {
275
/** Generated JavaScript code */
276
body: string;
277
/** Array of file dependencies */
278
dependencies: string[];
279
}
280
```