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 :heart: 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

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

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

(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md 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

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.