Options

The Liquid constructor accepts a plain object as options to define the behavior of LiquidJS. All of these options are optional thus we can specify any of them, for example the cache option:

const { Liquid } = require('liquidjs')
const engine = new Liquid({
    cache: true
})
API Document

Following is an overview for all the options, for exact types and signatures please refer to LiquidOptions | API.

cache

cache is used to improve performance by caching previously parsed template structures, specially in cases when we’re repeatedly parse or render files.

It’s default to false. When setting to true a default LRU cache of size 1024 will be enabled. And certainly it can be a number which indicates the size of cache you want.

Additionally, it can also be a custom cache implementation. See Caching for details.

Partials/Layouts

root is used to specify template directories for LiquidJS to lookup and read template files. Can be a single string and an array of strings. See Render Files for details.

layouts is used to specify template directories for LiquidJS to lookup files for {% layout %}. Same format as root and will default to root if not specified.

partials is used to specify template directories for LiquidJS to lookup files for {% render %} and {% include %}. Same format as root and will default to root if not specified.

relativeReference is set to true by default to allow relative filenames. Note that relatively referenced files are also need to be within corresponding root. For example you can reference another file like {% render ../foo/bar %} as long as ../foo/bar is also within partials directory.

dynamicPartials

Note: for historical reasons, it’s named dynamicPartials but it also works for layouts.

dynamicPartials indicates whether or not to treat filename arguments in include, render, layout tags as a variable. Defaults to true. For example, render the following snippet with scope { file: 'foo.html' } will include the foo.html:

{% include file %}

Setting dynamicPartials: false, LiquidJS will try to include the file named file, which is weird but allows simpler syntax if your template relations are static:

{% liquid foo.html %}
Common Pitfall

LiquidJS defaults this option to true to be compatible with shopify/liquid, but if you’re from eleventy it’s set to false by default (see Quoted Include Paths) which I believe is trying to be compatible with Jekyll.

Jekyll include

v9.33.0

jekyllInclude is used to enable Jekyll-like include syntax. Defaults to false, when set to true:

  • Filename will be static: dynamicPartials now defaults to false (instead of true). And you can set dynamicPartials back to true.
  • Use = instead of : to separate parameter key-values.
  • Parameters are under include variable instead of current scope.

For example in the following template, name.html is not quoted, header and "HEADER" are separated by =, and the header parameter is referenced by include.header. More details please check out include.

// entry template
{% include article.html header="HEADER" content="CONTENT" %}

// article.html
<article>
  <header>{{include.header}}</header>
  {{include.content}}
</article>

extname

extname defines the default extension name to be appended into filenames if the filename has no extension name. Defaults to '' which means it’s disabled by default. By setting it to .liquid:

{% render "foo" %}  there's no extname, adds `.liquid` and loads foo.liquid
{% render "foo.html" %}  there is an extname already, loads foo.html directly
Legacy Versions

Before 2.0.1, extname is set to .liquid by default. To change that you need to set extname: '' explicitly. See #41 for details.

fs

fs is used to define a custom file system implementation which will be used by LiquidJS to lookup and read template files. See Abstract File System for details.

globals

globals is used to define global variables available to all templates even in cases of render tag. See 3185 for details.

jsTruthy

jsTruthy is used to use standard JavaScript truthiness rather than the Shopify.

it defaults to false. For example, when set to true, a blank string would evaluate to false with jsTruthy. With Shopify’s truthiness, a blank string is true.

outputEscape

outputEscape can be used to automatically escape output strings. It can be one of "escape", "json", or (val: unknown) => string, defaults to undefined.

  • For untrusted output variables, set outputEscape: "escape" makes them be HTML escaped by default. You’ll need raw filter for direct output.
  • "json" is useful when you’re using LiquidJS to create valid JSON files.
  • It can even be a function which allows you to control what variables are output throughout LiquidJS. Please note the input can be any type other than string, e.g. an filter returned an non-string value.

Date

timezoneOffset is used to specify a different timezone to output dates, your local timezone will be used if not specified. For example, set timezoneOffset: 0 to output all dates in UTC/GMT 00:00.

preserveTimezones is a boolean effects only literal timestamps. When set to true, all literal timestamps will remain the same when output. This is a parser option, so Date objects passed to LiquidJS as data will not be affected. Note that preserveTimezones has a higher priority than timezoneOffset.

dateFormat is used to specify a default format to output dates. %A, %B %-e, %Y at %-l:%M %P %z will be used if not specified. For example, set dateFormat: %Y-%m-%dT%H:%M:%S:%LZ to output all dates in [JavaScript Date.toJson()][https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toJSON] format.

Trimming

greedy, trimOutputLeft, trimOutputRight, trimTagLeft, trimTagRight options are used to eliminate extra newlines and indents in templates around Liquid Constructs. See Whitespace Control for details.

Delimiter

outputDelimiterLeft, outputDelimiterRight, tagDelimiterLeft, tagDelimiterRight are used to customize the delimiters for LiquidJS Tags and Filters. For example with outputDelimiterLeft: <%=, outputDelimiterRight: %> we are able to avoid conflicts with other languages:

<%= username | append: ", welcome to LiquidJS!" %>

Strict

strictFilters is used to assert filter existence. If set to false, undefined filters will be skipped. Otherwise, undefined filters will cause a parse exception. Defaults to false.

strictVariables is used to assert variable existence. If set to false, undefined variables will be rendered as empty string. Otherwise, undefined variables will cause a render exception. Defaults to false.

lenientIf modifies the behavior of strictVariables to allow handling optional variables. If set to true, an undefined variable will not cause an exception in the following two situations: a) it is the condition to an if, elsif, or unless tag; b) it occurs right before a default filter. Irrelevant if strictVariables is not set. Defaults to false.

ownPropertyOnly hides scope variables from prototypes, useful when you’re passing a not sanitized object into LiquidJS or need to hide prototypes from templates. Defaults to true.

Nonexistent Tags

Nonexistent tags always throw errors during parsing and this behavior cannot be customized.

Parameter Order

Parameter orders are ignored by default, for ea {% for i in (1..8) reversed limit:3 %} will always perform limit before reversed, even if reversed occurs before limit. To make parameter order respected, set orderedFilterParameters to true. Its default value is false.