Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


    liquid-to-handlebars NPM version NPM monthly downloads NPM total downloads Linux Build Status

    Convert liquid templates to handlebars templates.

    Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your ❤️ and support.

    (TOC generated by verb using markdown-toc)


    Install with npm:

    $ npm install --save liquid-to-handlebars

    Why use this?

    If you've ever seen a jekyll boilerplate, or another project that uses liquid templates and wished it was written in handlebars, this is your solution!

    • 100% of the tags mentioned in the shopify liquid documentation convert to handlebars syntax
    • easily migrate any liquid theme or boilerplate
    • use more powerful and flexible handlebars helpers instead of liquid filters

    Please create an issue if you find a tag that doesn't convert correctly, and I'll add support. Thanks!


    const converter = require('liquid-to-handlebars');
    // Converts this liquid
    console.log(converter.convert('Price: ${{ product_price | default: 2.99 }}'));
    // To this handlebars
    //=> 'Price: ${{default product_price 2.99}}'

    You will also need to include any missing handlebars helpers that provide similar functionality to the liquid filters that are being replaced. For example:

    const handlebars = require('handlebars');
    handlebars.registerHelper('default', function(a, b) {
      return a || b || '';
    const fn = handlebars.compile('Price: ${{default product_price 2.99}}');
    //=> 'Price: $2.99'
    console.log(fn({default_price: '4.99'}));
    //=> 'Price: $4.99'

    Migration debugging

    Once your liquid templates are converted to handlebars, if you attempt to render all of the templates with handlebars without any additional work, it's a good bet that you'll receive a bunch of errors from missing helpers.

    Save yourself a bunch of time and frustration by following these steps:

    Step 1: Add starter helpers

    Add the following to your app:

    const handlebars = require('handlebars');
    // override handlebars' built-in `helperMissing` helper, so that we 
    // can easily see which helpers are missing and get them fixed
    handlebars.registerHelper('helperMissing', function() {
      const opts = [];
      console.log(`missing helper {{${}}}`);

    Step 2: Run handlebars

    Now, when you run handlebars, if you see a message like this:

    missing helper {{foo}}

    You can either create the foo helper from scratch, or use a helper library that already includes the helpers you need.

    Any of the following libraries may be used, but the [liquid-filters][] library might be most useful (during migration, at least).

    • [liquid-filters][] - includes a bunch of utility javascript functions that can be registered as handlebars helpers to provide parity with the built-in liquid filters
    • template-helpers - generic helpers that can be used with any template engine.
    • handlebars-helpers - more than 150 handlebars helpers


    const handlebars = require('handlebars');
    const filters = require('liquid-filters');
    const helpers = require('template-helpers');

    Conversion Examples

    There are many more examples in the docs folder, as well as test/fixtures and test/expected.


    basic operators

    From this liquid:

    {% if product.type == "Shirt" or product.type == "Shoes" %}
      This is a shirt or a pair of shoes.
    {% endif %}

    To this handlebars:

    {{#if (or (is product.type "Shirt") (is product.type "Shoes"))}}
      This is a shirt or a pair of shoes.


    From this liquid:

    {% if settings.fp_heading %}
      <h1>{{ settings.fp_heading }}</h1>
    {% endif %}

    To this handlebars:

    {{#if settings.fp_heading}}
      <h1>{{ settings.fp_heading }}</h1>


    From this liquid:

    {% case handle %}
    {% when 'cake' %}
      This is a cake
    {% when 'cookie' %}
      This is a cookie
    {% else %}
      This is not a cookie/cake
    {% endcase %}

    To this handlebars:

    {{#is handle 'cake'}}
      This is a cake
    {{else is handle 'cookie'}}
      This is a cookie
    {{ else }}
      This is not a cookie/cake

    Requires the "is" helper.


    From this liquid:

    {% if username and username.size > 10 %}
      Wow, {{ username }}, you have a long name!
    {% else %}
      Hello there!
    {% endif %}

    To this handlebars:

    {{#if (and username (gt username.size 10))}}
      Wow, {{ username }}, you have a long name!
      Hello there!


    From this liquid:

    {% if product.title contains 'Pack' %}
      This product's title contains the word Pack.
    {% endif %}

    To this handlebars:

    {{#if (contains product.title "Pack")}}
      This product's title contains the word Pack.


    Basic loops

    From this liquid:

    <!-- if site.users = "Tobi", "Laura", "Tetsuro", "Adam" -->
    {% for user in site.users %}
      {{ user }}
    {% endfor %}

    To this handlebars:

    <!-- if site.users = "Tobi", "Laura", "Tetsuro", "Adam" -->
    {{#each site.users as |user|}}
      {{ user }}

    Accessing specific items in arrays

    From this liquid:

    <!-- if site.users = "Tobi", "Laura", "Tetsuro", "Adam" -->
    {{ site.users[0] }}
    {{ site.users[1] }}
    {{ site.users[3] }}

    To this handlebars:

    <!-- if site.users = "Tobi", "Laura", "Tetsuro", "Adam" -->
    {{get site.users 0}}
    {{get site.users 1}}
    {{get site.users 3}}


    Filters are converted to handlebars subexpressions

    From this liquid:

    {{ "Ground control to Major Tom." | split: "" | reverse | join: "" }}

    To this handlebars:

    {{join (reverse (split "Ground control to Major Tom." "")) ""}}

    Many more examples in the docs folder and unit tests.

    What is this?

    This is a tool for converting projects that use liquid templates to use handlebars templates.



    Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

    Running Tests

    Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

    $ npm install && npm test
    Building docs

    (This project's is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the readme template.)

    To generate the readme, run the following command:

    $ npm install -g verbose/verb#dev verb-generate-readme && verb

    Related projects

    You might also be interested in these projects:

    • assemble: Get the rocks out of your socks! Assemble makes you fast at creating web projects… more | homepage
    • handlebars: Handlebars provides the power necessary to let you build semantic templates effectively with no frustration | homepage


    Jon Schlinkert


    Copyright © 2018, Jon Schlinkert. Released under the MIT License.

    This file was generated by verb-generate-readme, v0.6.0, on May 06, 2018.


    npm i liquid-to-handlebars

    Downloadsweekly downloads








    last publish


    • avatar