FlareLane Liquid

A lightweight wrapper around LiquidJS for safe and controlled template interpolation.

Overview

FlareLane Liquid is a library for parsing and rendering Liquid templates with an emphasis on safety and control. It provides a simplified API for LiquidJS with added features like whitelisted filters and tags, custom filters, and template preprocessing.

Installation

npm install @flarelane/liquid

or

yarn add @flarelane/liquid

Usage

Basic Usage

import { Liquid } from '@flarelane/liquid';

// Use the singleton instance
const liquid = Liquid.shared;

// Interpolate a template with data
const result = liquid.interpolate('Hello {{ name }}!', { name: 'World' });
// result: "Hello World!"

// Parse variables from a template
const variables = liquid.parse('Hello {{ name }}, today is {{ date }}');
// variables: ['name', 'date']

Custom Configuration

You can create a custom instance with your own configuration:

const customLiquid = new Liquid({
  supportedFilters: ['escape', 'default', 'upcase'],
  supportedTags: ['if'],
});

Features

Whitelisted Filters and Tags

By default, FlareLane Liquid only allows a safe subset of LiquidJS filters and tags. Attempts to use unsupported filters or tags will throw an error.

Default supported filters:

• Basic filters: escape, uri_escape, url_encode, url_decode, strip_html, default
• Text manipulation: upcase, downcase, capitalize, truncate, truncatewords, replace, replace_first
• Date: date
• Math: plus, minus, times, divided_by, round, floor, ceil

Default supported tags:

• if, unless

Custom Filters

FlareLane Liquid includes additional custom filters:

• number_with_delimiter: Formats numbers with thousand separators (e.g., 1,000,000)
• printable: Ensures output is a primitive type (string, number, boolean)

Template Preprocessing

FlareLane Liquid includes a template preprocessor that supports shortened syntax for the default filter:

{{ variable || default_value }}

This is automatically converted to:

{{ variable | default: "default_value" }}

License

MIT