0
# Configuration
1

2
LiquidJS provides comprehensive configuration options through the LiquidOptions interface, enabling fine-tuned control over template processing, file handling, performance limits, and output formatting.
3

4
## Capabilities
5

6
### LiquidOptions Interface
7

8
Main configuration interface for customizing LiquidJS behavior.
9

10
```typescript { .api }
11
interface LiquidOptions {
12
  // File System Configuration
13
  root?: string | string[];
14
  partials?: string | string[];
15
  layouts?: string | string[];
16
  fs?: FS;
17
  relativeReference?: boolean;
18
  extname?: string;
19
  templates?: {[key: string]: string};
20

21
  // Template Processing
22
  strictFilters?: boolean;
23
  strictVariables?: boolean;
24
  dynamicPartials?: boolean;
25
  jekyllInclude?: boolean;
26
  jekyllWhere?: boolean;
27
  jsTruthy?: boolean;
28
  lenientIf?: boolean;
29
  ownPropertyOnly?: boolean;
30
  catchAllErrors?: boolean;
31

32
  // Output Control
33
  outputEscape?: 'escape' | 'json' | ((value: any) => string);
34
  keepOutputType?: boolean;
35
  trimTagRight?: boolean;
36
  trimTagLeft?: boolean;
37
  trimOutputRight?: boolean;
38
  trimOutputLeft?: boolean;
39
  greedy?: boolean;
40

41
  // Delimiters
42
  tagDelimiterLeft?: string;
43
  tagDelimiterRight?: string;
44
  outputDelimiterLeft?: string;
45
  outputDelimiterRight?: string;
46

47
  // Internationalization
48
  timezoneOffset?: number | string;
49
  dateFormat?: string;
50
  locale?: string;
51
  preserveTimezones?: boolean;
52

53
  // Caching
54
  cache?: boolean | number | LiquidCache;
55

56
  // Performance Limits
57
  parseLimit?: number;
58
  renderLimit?: number;
59
  memoryLimit?: number;
60

61
  // Advanced
62
  globals?: object;
63
  operators?: Operators;
64
  keyValueSeparator?: string;
65
  orderedFilterParameters?: boolean;
66
}
67
```
68

69
### File System Configuration
70

71
Control how templates are loaded from the file system.
72

73
```typescript { .api }
74
/**
75
 * Root directories for template resolution
76
 * Default: ["."]
77
 */
78
root?: string | string[];
79

80
/**
81
 * Directories for partial template resolution
82
 * Default: same as root
83
 */
84
partials?: string | string[];
85

86
/**
87
 * Directories for layout template resolution
88
 * Default: same as root
89
 */
90
layouts?: string | string[];
91

92
/**
93
 * Custom file system implementation
94
 */
95
fs?: FS;
96

97
/**
98
 * Allow relative pathname references
99
 * Default: true
100
 */
101
relativeReference?: boolean;
102

103
/**
104
 * Default file extension for template lookup
105
 * Default: ""
106
 */
107
extname?: string;
108

109
/**
110
 * In-memory template mapping (overrides file system)
111
 */
112
templates?: {[key: string]: string};
113
```
114

115
**Usage Examples:**
116

117
```typescript
118
import { Liquid } from "liquidjs";
119

120
// File system configuration
121
const engine = new Liquid({
122
  root: ["./templates", "./shared"],
123
  partials: "./partials",
124
  layouts: "./layouts",
125
  extname: ".liquid"
126
});
127

128
// In-memory templates
129
const memoryEngine = new Liquid({
130
  templates: {
131
    "header": "<h1>{{ title }}</h1>",
132
    "footer": "<p>© {{ year }}</p>"
133
  }
134
});
135
```
136

137
### Template Processing
138

139
Control template parsing and rendering behavior.
140

141
```typescript { .api }
142
/**
143
 * Assert filter existence (throw error for undefined filters)
144
 * Default: false
145
 */
146
strictFilters?: boolean;
147

148
/**
149
 * Assert variable existence (throw error for undefined variables)
150
 * Default: false
151
 */
152
strictVariables?: boolean;
153

154
/**
155
 * Treat include/layout filepath as variable
156
 * Default: true
157
 */
158
dynamicPartials?: boolean;
159

160
/**
161
 * Use Jekyll-style includes with parameter passing
162
 * Default: false
163
 */
164
jekyllInclude?: boolean;
165

166
/**
167
 * Enable Jekyll-style where filter for array matching
168
 * Default: false
169
 */
170
jekyllWhere?: boolean;
171

172
/**
173
 * Use JavaScript truthiness evaluation
174
 * Default: false
175
 */
176
jsTruthy?: boolean;
177

178
/**
179
 * Allow undefined variables in conditionals
180
 * Default: false
181
 */
182
lenientIf?: boolean;
183

184
/**
185
 * Hide prototype properties from scope
186
 * Default: true
187
 */
188
ownPropertyOnly?: boolean;
189

190
/**
191
 * Continue processing after errors instead of stopping
192
 * Default: false
193
 */
194
catchAllErrors?: boolean;
195
```
196

197
**Usage Examples:**
198

199
```typescript
200
// Strict mode for development
201
const strictEngine = new Liquid({
202
  strictFilters: true,
203
  strictVariables: true,
204
  catchAllErrors: false
205
});
206

207
// Lenient mode for production
208
const lenientEngine = new Liquid({
209
  strictFilters: false,
210
  strictVariables: false,
211
  lenientIf: true,
212
  catchAllErrors: true
213
});
214

215
// Jekyll compatibility
216
const jekyllEngine = new Liquid({
217
  jekyllInclude: true,
218
  jekyllWhere: true,
219
  dynamicPartials: false
220
});
221
```
222

223
### Output Control
224

225
Configure template output formatting and escaping.
226

227
```typescript { .api }
228
/**
229
 * Default escape function for all outputs
230
 * Options: 'escape', 'json', or custom function
231
 * Default: undefined (no escaping)
232
 */
233
outputEscape?: 'escape' | 'json' | ((value: any) => string);
234

235
/**
236
 * Preserve original data types in output
237
 * Default: false (convert to strings)
238
 */
239
keepOutputType?: boolean;
240

241
/**
242
 * Trim whitespace after tags until newline
243
 * Default: false
244
 */
245
trimTagRight?: boolean;
246

247
/**
248
 * Trim whitespace before tags until newline
249
 * Default: false
250
 */
251
trimTagLeft?: boolean;
252

253
/**
254
 * Trim whitespace after outputs until newline
255
 * Default: false
256
 */
257
trimOutputRight?: boolean;
258

259
/**
260
 * Trim whitespace before outputs until newline
261
 * Default: false
262
 */
263
trimOutputLeft?: boolean;
264

265
/**
266
 * Aggressive whitespace trimming (all consecutive whitespace)
267
 * Default: true
268
 */
269
greedy?: boolean;
270
```
271

272
**Usage Examples:**
273

274
```typescript
275
// HTML escaping by default
276
const htmlEngine = new Liquid({
277
  outputEscape: 'escape'
278
});
279

280
// Custom escaping function
281
const customEngine = new Liquid({
282
  outputEscape: (value) => String(value).replace(/</g, '&lt;')
283
});
284

285
// Whitespace control
286
const cleanEngine = new Liquid({
287
  trimTagLeft: true,
288
  trimTagRight: true,
289
  trimOutputLeft: true,
290
  trimOutputRight: true,
291
  greedy: true
292
});
293
```
294

295
### Custom Delimiters
296

297
Customize tag and output delimiters.
298

299
```typescript { .api }
300
/**
301
 * Left delimiter for tags
302
 * Default: "{%"
303
 */
304
tagDelimiterLeft?: string;
305

306
/**
307
 * Right delimiter for tags
308
 * Default: "%}"
309
 */
310
tagDelimiterRight?: string;
311

312
/**
313
 * Left delimiter for outputs
314
 * Default: "{{"
315
 */
316
outputDelimiterLeft?: string;
317

318
/**
319
 * Right delimiter for outputs
320
 * Default: "}}"
321
 */
322
outputDelimiterRight?: string;
323
```
324

325
**Usage Examples:**
326

327
```typescript
328
// Custom delimiters
329
const customDelimiters = new Liquid({
330
  tagDelimiterLeft: "<%",
331
  tagDelimiterRight: "%>",
332
  outputDelimiterLeft: "<%=",
333
  outputDelimiterRight: "%>"
334
});
335

336
// Templates now use: <% if condition %>...<%=%> value <%=>...<%/%>
337
```
338

339
### Performance Limits
340

341
Configure performance and DoS protection limits.
342

343
```typescript { .api }
344
/**
345
 * Maximum template length to parse in one call
346
 * Default: Infinity
347
 */
348
parseLimit?: number;
349

350
/**
351
 * Maximum render time in milliseconds
352
 * Default: Infinity
353
 */
354
renderLimit?: number;
355

356
/**
357
 * Maximum memory usage for operations
358
 * Default: Infinity
359
 */
360
memoryLimit?: number;
361
```
362

363
**Usage Examples:**
364

365
```typescript
366
// Production safety limits
367
const safeEngine = new Liquid({
368
  parseLimit: 1_000_000,     // 1MB template limit
369
  renderLimit: 5_000,        // 5 second render limit
370
  memoryLimit: 100_000_000   // 100MB memory limit
371
});
372
```
373

374
### Caching
375

376
Configure template caching for improved performance.
377

378
```typescript { .api }
379
/**
380
 * Template caching configuration
381
 * - false: no caching
382
 * - true: default LRU cache (1024 entries)
383
 * - number: LRU cache with specified size
384
 * - LiquidCache: custom cache implementation
385
 */
386
cache?: boolean | number | LiquidCache;
387

388
interface LiquidCache {
389
  lookup(key: string): Template[] | undefined;
390
  assign(key: string, value: Template[]): void;
391
  remove(key: string): void;
392
  clear(): void;
393
}
394
```
395

396
**Usage Examples:**
397

398
```typescript
399
// Enable default caching
400
const cachedEngine = new Liquid({
401
  cache: true
402
});
403

404
// Custom cache size
405
const largeCacheEngine = new Liquid({
406
  cache: 5000
407
});
408

409
// Custom cache implementation
410
class CustomCache implements LiquidCache {
411
  private store = new Map<string, Template[]>();
412
  
413
  lookup(key: string) { return this.store.get(key); }
414
  assign(key: string, value: Template[]) { this.store.set(key, value); }
415
  remove(key: string) { this.store.delete(key); }
416
  clear() { this.store.clear(); }
417
}
418

419
const customCacheEngine = new Liquid({
420
  cache: new CustomCache()
421
});
422
```
423

424
### Internationalization
425

426
Configure date formatting and locale settings.
427

428
```typescript { .api }
429
/**
430
 * Timezone offset for date operations
431
 * Can be number (minutes) or timezone name
432
 * Default: local timezone
433
 */
434
timezoneOffset?: number | string;
435

436
/**
437
 * Default date format string
438
 * Default: "%A, %B %-e, %Y at %-l:%M %P %z"
439
 */
440
dateFormat?: string;
441

442
/**
443
 * Default locale for date formatting
444
 * Default: system locale
445
 */
446
locale?: string;
447

448
/**
449
 * Preserve input timezone in date operations
450
 * Default: false
451
 */
452
preserveTimezones?: boolean;
453
```
454

455
**Usage Examples:**
456

457
```typescript
458
// Timezone and locale configuration
459
const i18nEngine = new Liquid({
460
  timezoneOffset: "America/New_York",
461
  dateFormat: "%Y-%m-%d %H:%M:%S",
462
  locale: "en-US",
463
  preserveTimezones: true
464
});
465
```
466

467
## Default Configuration
468

469
```typescript { .api }
470
const defaultOptions: NormalizedFullOptions = {
471
  root: ['.'],
472
  layouts: ['.'],
473
  partials: ['.'],
474
  relativeReference: true,
475
  jekyllInclude: false,
476
  cache: undefined,
477
  extname: '',
478
  dynamicPartials: true,
479
  jsTruthy: false,
480
  dateFormat: '%A, %B %-e, %Y at %-l:%M %P %z',
481
  locale: '',
482
  trimTagRight: false,
483
  trimTagLeft: false,
484
  trimOutputRight: false,
485
  trimOutputLeft: false,
486
  greedy: true,
487
  tagDelimiterLeft: '{%',
488
  tagDelimiterRight: '%}',
489
  outputDelimiterLeft: '{{',
490
  outputDelimiterRight: '}}',
491
  preserveTimezones: false,
492
  strictFilters: false,
493
  strictVariables: false,
494
  ownPropertyOnly: true,
495
  lenientIf: false,
496
  globals: {},
497
  keepOutputType: false,
498
  memoryLimit: Infinity,
499
  parseLimit: Infinity,
500
  renderLimit: Infinity
501
};
502
```