liquidjs

What is liquidjs?

LiquidJS is a JavaScript implementation of the Liquid templating language, which was originally created by Shopify. It allows you to render dynamic content in your web applications by using a simple and readable syntax. LiquidJS is highly extensible and can be used both on the server-side with Node.js and in the browser.

What are liquidjs's main functionalities?

Basic Template Rendering

This feature allows you to render basic templates with dynamic content. In this example, the template 'Hello, {{name}}!' is rendered with the variable 'name' set to 'World', resulting in 'Hello, World!'.

const { Liquid } = require('liquidjs');
const engine = new Liquid();
const template = 'Hello, {{name}}!';
engine.parseAndRender(template, { name: 'World' }).then(console.log);

Loops

This feature allows you to iterate over arrays and render each item. In this example, the template iterates over the 'items' array and renders each item, resulting in 'apple banana cherry '.

const { Liquid } = require('liquidjs');
const engine = new Liquid();
const template = '{% for item in items %}{{ item }} {% endfor %}';
engine.parseAndRender(template, { items: ['apple', 'banana', 'cherry'] }).then(console.log);

Conditionals

This feature allows you to use conditional statements in your templates. In this example, the template checks if the 'user' variable exists and renders 'Hello, Alice!' if it does, otherwise it renders 'Hello, Guest!'.

const { Liquid } = require('liquidjs');
const engine = new Liquid();
const template = '{% if user %}Hello, {{ user.name }}!{% else %}Hello, Guest!{% endif %}';
engine.parseAndRender(template, { user: { name: 'Alice' } }).then(console.log);

Filters

This feature allows you to use filters to transform output. In this example, the 'upcase' filter is used to convert the string 'hello' to uppercase, resulting in 'HELLO'.

const { Liquid } = require('liquidjs');
const engine = new Liquid();
const template = '{{ "hello" | upcase }}';
engine.parseAndRender(template).then(console.log);

Other packages similar to liquidjs

nunjucks

Nunjucks is a powerful templating engine for JavaScript, inspired by Jinja2. It offers a similar feature set to LiquidJS, including template inheritance, macros, and filters. Nunjucks is known for its flexibility and ease of use, making it a strong alternative to LiquidJS.

handlebars

Handlebars is a popular templating engine that provides a simple way to build semantic templates. It supports features like nested templates, partials, and helpers. Handlebars is known for its simplicity and performance, making it a good choice for projects that require straightforward templating.

ejs

EJS (Embedded JavaScript) is a templating engine that lets you generate HTML with plain JavaScript. It supports features like partials and includes, and is known for its simplicity and ease of integration with Express.js. EJS is a good option for developers who prefer a more JavaScript-centric approach to templating.

README

liquidjs

A shopify compatible Liquid template engine in pure JavaScript. The purpose of this repo is to provide a standard Liquid implementation for the JavaScript community. All features, filters and tags in shopify/liquid are supposed to be built in LiquidJS, though there are still some differences and limitations (see below).

Version 9 has published, see how to migrate to 9.0.0!

Get Started

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'

Or include the UMD build, a live demo is available on jsfiddle: https://jsfiddle.net/x43eb0z6/. You may need a Promise polyfill for Node.js < 4 and ES5 browsers like IE and Android UC.

<script src="//unpkg.com/liquidjs/dist/liquid.min.js"></script>     <!--for production-->
<script src="//unpkg.com/liquidjs/dist/liquid.js"></script>         <!--for development-->

Also available from CLI:

echo '{{"hello" | capitalize}}' | npx liquidjs

For detailed documents, see:

• The Wiki Page contains tutorials and advanced topics.
• The API Reference provides detailed descriptions for classes, methods and properties.

Differences and Limitations

• Dynamic file locating (enabled by default), that means layout/partial names are treated as variables in liquidjs. See #51.
• Truthy and Falsy. All values except undefined, null, false are truthy, whereas in Ruby Liquid all except nil and false are truthy. See #26.
• Number. In JavaScript we cannot distinguish or convert between float and integer, see #59. And when applied size filter, numbers always return 0, which is 8 for integer in ruby, cause they do not have a length property.
• .to_liquid() is replaced by .toLiquid()
• .to_s() is replaced by JavaScript .toString()

Features that available on shopify website but not on shopify/liquid repo will not be implemented in this repo, but there're some plugins available: https://github.com/harttle/liquidjs/wiki/Plugins

Related Packages

• gulp-liquidjs: A shopify compatible Liquid template engine for Gulp using liquidjs.
• grunt-liquify: A Grunt task to process Liquid using liquidjs. Use it to add Liquid magic to your scripts and css assets.
• react-liquid: Liquid templating language component for React
• @11ty/eleventy: A simpler static site generator. An alternative to Jekyll. Written in JavaScript. Transforms a directory of templates (of varying types) into HTML.

Contribute Guidelines

• Code Style: https://github.com/standard/eslint-config-standard, npm run lint to check locally.
• Testing: make sure test cases still pass, use npm test to check locally.
• Commit Message: align to The Angular Commit Message Guidelines, especially the Type identifier, to allow the semantic-release bot do the work.

Contributors ✨

This project follows the all-contributors specification. Contributions of any kind are welcome! Thanks goes to these wonderful people:

Jun Yang 🚧 💻	chenos 💻	Zach Leatherman 🐛	Tim Hardy 💻	Paul Robert Lloyd 💻 🐛	Alec Larson 💻	Patrick Malouin 💻 📖
jaswrks 💻	三三 💻 🤔	ssendev 💻 📖	wojtask9 💻	Andrew Barclay 💻	Cory Mawhorter 💻	Mehdi Jaffery 💻
Robin Bijlani 💻 🐛	Ryan Kennedy 💻	Sami Kukkonen 💻	Scott Santucci 💻	Steven 💡 💻	azu 📖	Joonas 💻
Jamel A. 💻

Changelog

9.3.0 (2019-11-07)

Features

• support require.resolve for lookup, see #168 (2dd4355)