liquidjs/docs/source/tutorials/setup.md

title

title
Setup

In case you're not familiar with Liquid Template Language, see Introduction to Liquid Template Language.

LiquidJS in Node.js

Install via npm:

npm install --save liquidjs

var { Liquid } = require('liquidjs');
var engine = new Liquid();

engine
    .parseAndRender('{{name | capitalize}}', {name: 'alice'})
    .then(console.log);     // outputs 'Alice'

{% note info Working Demo %} Here's a working demo for LiquidJS usage in Node.js: liquidjs/demo/nodejs/.{% endnote %}

Type definitions for LiquidJS are also exported and published, which makes it more enjoyable for TypeScript projects:

import { Liquid } from 'liquidjs';
const engine = new Liquid();

engine
    .parseAndRender('{{name | capitalize}}', {name: 'alice'})
    .then(console.log);     // outputs 'Alice'

{% note info Working Demo %} Here's a working demo for LiquidJS usage in TypeScript: liquidjs/demo/typescript/.{% endnote %}

LiquidJS in Browsers

Pre-built UMD bundles are also available:

<!--for production-->
<script src="https://cdn.jsdelivr.net/npm/liquidjs/dist/liquid.browser.min.js"></script>
<!--for development-->
<script src="https://cdn.jsdelivr.net/npm/liquidjs/dist/liquid.browser.umd.js"></script>

{% note info Working Demo %} Here's a living demo on jsFiddle: jsfiddle.net/pd4jhzLs/1/, and the source code is also available in liquidjs/demo/browser/.{% endnote %}

{% note warn Compatibility %} You may need a Promise polyfill for legacy browsers like IE and Android UC, see caniuse statistics. {% endnote %}

LiquidJS in CLI

LiquidJS can also be used to render a template directly from CLI using npx:

npx liquidjs --template '{{"hello" | capitalize}}'

You can either pass the template inline (as shown above) or you can read it from a file by using the @ character followed by a path, like so:

npx liquidjs --template @./some-template.liquid

You can also use the @- syntax to read the template from stdin:

echo '{{"hello" | capitalize}}' | npx liquidjs --template @-

A context can be passed in the same ways (i.e. inline, from a path or piped through stdin). The following three are equivalent:

npx liquidjs --template 'Hello, {{ name }}!' --context '{"name": "Snake"}'
npx liquidjs --template 'Hello, {{ name }}!' --context @./some-context.json
echo '{"name": "Snake"}' | npx liquidjs --template 'Hello, {{ name }}!' --context @-

Note that you can only use the stdin specifier @- for a single argument. If you try to use it for both --template and --context you will get an error.

The rendered output is written to stdout by default, but you can also specify an output file (if the file exists, it will be overwritten):

npx liquidjs --template '{{"hello" | capitalize}}' --output ./hello.txt

You can also pass a number of options to customize template rendering behavior. For example, the --js-truthy option can be used to enable JavaScript truthiness:

npx liquidjs --template @./some-template.liquid --js-truthy

Most of the options available through the JavaScript API are also available from the CLI. For help on available options, use npx liquidjs --help.

Miscellaneous

A ReactJS demo is also added by @stevenanthonyrevo, see liquidjs/demo/reactjs/.