liquid-to-handlebars

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.

• Install
• Why use this?
• Usage
• Migration debugging
  • Step 1: Add starter helpers
  • Step 2: Run handlebars
• Conversion Examples
  • Conditionals
  • Arrays
  • Filters
• What is this?
• About

(TOC generated by verb using markdown-toc)

Install

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!

Usage

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}}');
console.log(fn());
//=> '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 = [].slice.call(arguments).pop();
  console.log(`missing helper {{${opts.name}}}`);
});

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

Examples

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

Conversion Examples

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

Conditionals

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.
{{/if}}

boolean

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>
{{/if}}

case

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
{{/is}}

Requires the "is" helper.

else

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!
{{else}}
  Hello there!
{{/if}}

contains

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.
{{/if}}

Arrays

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 }}
{{/each}}

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

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.

About

$ npm install && npm test

$ 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

Author

Jon Schlinkert

• LinkedIn Profile
• GitHub Profile
• Twitter Profile

License

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

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