The Liquid constructor accepts a plain object as options to define the behaviour 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 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.


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.


extname defines the default extname to be appended into filenames if the filename has no extname. 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.


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.


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 is used to define global variables available to all templates even in cases of render tag. See 3185 for details.


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.


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


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!" %>


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.

Non-existent Tags

Non-existent tags always throw errors during pasrsing and this behaviour can not be customized.