0
# Template Compilation
1

2
Core compilation functionality for transforming Pug templates into executable JavaScript functions. This provides maximum performance for production applications by pre-compiling templates into reusable functions.
3

4
## Capabilities
5

6
### Compile Function
7

8
Compiles a Pug template string into a reusable template function.
9

10
```javascript { .api }
11
/**
12
 * Compile a Pug template string into a function
13
 * @param str - Pug template source code
14
 * @param options - Compilation options
15
 * @returns Template function that accepts locals and returns HTML string
16
 */
17
function compile(str, options);
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
const pug = require('pug');
24

25
// Basic compilation
26
const template = pug.compile('p Hello #{name}!');
27
const html = template({ name: 'World' });
28
// Result: <p>Hello World!</p>
29

30
// With options
31
const template2 = pug.compile(`
32
doctype html
33
html
34
  head
35
    title= title
36
  body
37
    h1= heading
38
    p= message
39
`, {
40
  pretty: true,
41
  compileDebug: false
42
});
43

44
const html2 = template2({
45
  title: 'My App',
46
  heading: 'Welcome',
47
  message: 'Hello from Pug!'
48
});
49
```
50

51
### Compile File Function
52

53
Compiles a Pug template file into a reusable template function with automatic caching support.
54

55
```javascript { .api }
56
/**
57
 * Compile a Pug template file into a function
58
 * @param path - Path to Pug template file
59
 * @param options - Compilation options
60
 * @returns Template function with caching support
61
 */
62
function compileFile(path, options);
63
```
64

65
**Usage Examples:**
66

67
```javascript
68
const pug = require('pug');
69

70
// Compile from file
71
const template = pug.compileFile('./views/layout.pug');
72
const html = template({ user: 'Alice', posts: [] });
73

74
// With caching enabled
75
const template2 = pug.compileFile('./views/user.pug', {
76
  cache: true,
77
  pretty: true
78
});
79

80
// Template will be cached and reused on subsequent calls
81
const html2 = template2({ user: { name: 'Bob', email: 'bob@example.com' } });
82
```
83

84
### Template Function Interface
85

86
The compiled template functions returned by `compile` and `compileFile` have the following interface:
87

88
```javascript { .api }
89
/**
90
 * Compiled template function
91
 * @param locals - Variables to make available in the template
92
 * @returns Rendered HTML string
93
 */
94
type TemplateFunction = (locals?: any) => string;
95

96
/**
97
 * Template functions include a dependencies property for file-based templates
98
 */
99
interface CompiledTemplate extends TemplateFunction {
100
  /** Array of file paths that this template depends on (includes/extends) */
101
  dependencies?: string[];
102
}
103
```
104

105
### Compilation Options
106

107
All compilation functions accept these options:
108

109
```javascript { .api }
110
interface CompilationOptions {
111
  /** Used for error reporting and resolving includes/extends */
112
  filename?: string;
113
  /** Include debugging information (default: true) */
114
  compileDebug?: boolean;
115
  /** Add pretty-indentation to output (default: false) */
116
  pretty?: boolean;
117
  /** Base directory for resolving includes and extends */
118
  basedir?: string;
119
  /** Set default doctype if not specified in template */
120
  doctype?: string;
121
  /** Custom filters for template processing */
122
  filters?: { [name: string]: Function };
123
  /** Options passed to filters */
124
  filterOptions?: any;
125
  /** Aliases for filter names */
126
  filterAliases?: { [alias: string]: string };
127
  /** Variables to make available globally in templates */
128
  globals?: string[];
129
  /** Use self namespace for locals (default: false) */
130
  self?: boolean;
131
  /** Inline runtime functions in generated code */
132
  inlineRuntimeFunctions?: boolean;
133
  /** Array of compilation plugins */
134
  plugins?: PugPlugin[];
135
  /** Include source maps in debug builds */
136
  includeSources?: boolean;
137
  /** Name for the generated template function */
138
  templateName?: string;
139
  /** Debug compilation process to console */
140
  debug?: boolean;
141
}
142
```
143

144
### Advanced Usage
145

146
**Template Inheritance:**
147

148
```javascript
149
// parent.pug
150
const parentTemplate = pug.compile(`
151
doctype html
152
html
153
  head
154
    title= title
155
  body
156
    block content
157
`);
158

159
// child.pug extends parent.pug
160
const childTemplate = pug.compileFile('./child.pug', {
161
  basedir: './views'
162
});
163
```
164

165
**Custom Filters:**
166

167
```javascript
168
const template = pug.compile('p: :markdown # Hello World', {
169
  filters: {
170
    markdown: function(text) {
171
      return require('markdown-it')().render(text);
172
    }
173
  }
174
});
175
```
176

177
**Plugin Usage:**
178

179
```javascript
180
const myPlugin = {
181
  postParse: function(ast, options) {
182
    // Modify the AST after parsing
183
    return ast;
184
  }
185
};
186

187
const template = pug.compile('p Hello World', {
188
  plugins: [myPlugin]
189
});
190
```
191

192
### Error Handling
193

194
Compilation can throw errors for:
195

196
- Syntax errors in Pug templates
197
- Missing files when using includes/extends
198
- Plugin conflicts or errors
199
- Invalid options
200

201
```javascript
202
try {
203
  const template = pug.compile('invalid pug syntax here {{}}');
204
} catch (err) {
205
  console.error('Compilation error:', err.message);
206
  console.error('Line:', err.line);
207
  console.error('Column:', err.column);
208
}
209
```