# liquidjs
[](https://www.npmjs.org/package/liquidjs)
[](https://www.npmjs.org/package/liquidjs)
[](https://coveralls.io/github/harttle/liquidjs?branch=master)
[](https://travis-ci.org/harttle/liquidjs)
[](https://github.com/harttle/liquidjs/issues)
[](https://github.com/harttle/liquidjs/graphs/contributors)
[](https://opencollective.com/liquidjs)
[](https://david-dm.org/harttle/liquidjs)
[](https://david-dm.org/harttle/liquidjs?type=dev)
[](https://github.com/harttle/liquidjs/blob/master/LICENSE)
[](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits)
[](https://github.com/harttle/liquidjs)
A simple, expressive, safe and [shopify][shopify/liquid] compatible template engine in pure JavaScript.
**The purpose of this repo** is to provide a standard Liquid implementation for the JavaScript community.
* [Jekyll sites](https://jekyllrb.com), [Github Pages](https://pages.github.com/) and [Shopify templates](https://themes.shopify.com/) can be ported to Node.js without pain.
* All features, filters and tags in [shopify/liquid](https://github.com/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](https://github.com/harttle/liquidjs/wiki/Migrate-to-9)!
## Get Started
Install via npm:
```bash
npm install --save liquidjs
```
```javascript
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: . You may need a [Promise polyfill][pp] for Node.js < 4 and ES5 browsers like [IE and Android UC][caniuse-promises].
```html
```
Also available from CLI:
```bash
echo '{{"hello" | capitalize}}' | npx liquidjs
```
For detailed documents, see:
* The [Wiki Page](https://github.com/harttle/liquidjs/wiki) contains tutorials and advanced topics.
* The [API Reference](https://harttle.github.io/liquidjs/classes/_liquid_.liquid.html) 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](https://github.com/harttle/liquidjs/issues/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](https://github.com/harttle/liquidjs/pull/26).
* Number. In JavaScript we cannot distinguish or convert between `float` and `integer`, see [#59](https://github.com/harttle/liquidjs/issues/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()](https://github.com/Shopify/liquid/wiki/Introduction-to-Drops) is replaced by `.toLiquid()`
* [.to_s()](https://www.rubydoc.info/gems/liquid/Liquid/Drop) is replaced by JavaScript `.toString()`
* Iteration order for objects. The iteration order of JavaScript objects, and thus LiquidJS objects, is a combination of the insertion order for string keys, and ascending order for number-like keys, while the iteration order of Ruby Hash is simply the insertion order.
* Sort stability. The [sort](https://shopify.github.io/liquid/filters/sort/) stability is also not defined in both shopify/liquid and LiquidJS, but it's [considered stable](https://v8.dev/features/stable-sort) for LiquidJS in Node.js 12+ and Google Chrome 70+.
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:
## Related Packages
* [gulp-liquidjs](https://www.npmjs.com/package/@tuanpham-dev/gulp-liquidjs): A shopify compatible Liquid template engine for Gulp using liquidjs.
* [grunt-liquify](https://www.npmjs.com/package/grunt-liquify): A Grunt task to process Liquid using liquidjs. Use it to add Liquid magic to your scripts and css assets.
* [react-liquid](https://github.com/aquibm/react-liquid#readme): Liquid templating language component for React
* [@11ty/eleventy](https://www.npmjs.com/package/@11ty/eleventy): A simpler static site generator. An alternative to Jekyll. Written in JavaScript. Transforms a directory of templates (of varying types) into HTML.
## Backers
Love LiquidJS and want to contribute? [Become a backer](https://opencollective.com/liquidjs).
## Contributors β¨
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification.
Contributions of any [kind](https://allcontributors.org/docs/en/emoji-key) are welcome!
Thanks goes to these wonderful people:
## Contribute Guideline
* **Code Style**: , `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](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits), especially the [Type identifier](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#type), to allow the semantic-release bot do the work.
[shopify/liquid]: https://shopify.github.io/liquid/
[caniuse-promises]: http://caniuse.com/#feat=promises
[pp]: https://github.com/taylorhakes/promise-polyfill
[tutorial]: https://shopify.github.io/liquid/basics/introduction/
