LiquidScript

LiquidScript is a JavaScript engine for the Liquid template language, written in TypeScript. We follow Shopify/Liquid closely and test against the Golden Liquid test suite.

This page gets you started using Liquid with JavaScript. See Liquid syntax, the filter reference and the tag reference to learn about writing Liquid templates.

Install

Install LiquidScript using your preferred project manager:

npm

npm install --save liquidscript

yarn

yarn add liquidscript

pnpm

pnpm add liquidscript

bun

bun add liquidscript

And import the module:

ESM

import * as liquid from "liquidscript";
const template = liquid.parse("Hello, {{ you }}!");

CJS

const liquid = require("liquidscript");
const template = liquid.parse("Hello, {{ you }}!");

Or, without the liquid namespace:

ESM

import { parse } from "liquidscript";
const template = parse("Hello, {{ you }}!");

CJS

const { parse } = require("liquidscript");
const template = parse("Hello, {{ you }}!");

Browser

Download and import LiquidScript in a script tag with type="module":

<script type="module">
  import * as liquid from "./liquidscript.browser.esm.min.js";

  const template = liquid.parse("Hello, {{ you }}!");
  template.render({ you: "World" }).then(console.log);
  template.render({ you: "Liquid" }).then(console.log);
</script>

Quick start

Render

Render a template using the top-level render() or renderSync() functions.

Properties from the object passed to render() and renderSync() are available for templates to use in Liquid expressions.

import { render, renderSync } from "liquidscript";

const source = "Hello, {{ you }}!";

// Sync
console.log(renderSync(source, { you: "World" })); // Hello, World!
console.log(renderSync(source, { you: "Liquid" })); // Hello, Liquid!

// Async
render(source, { you: "World" }).then(console.log); // Hello, World!
render(source, { you: "Liquid" }).then(console.log); // Hello, Liquid!

// Or, using await
(async () => {
  console.log(await render(source, { you: "World" })); // Hello, World!
  console.log(await render(source, { you: "Liquid" })); // Hello, Liquid!
})();

Parse

Often you'll want to render the same template several times with different variables. We can parse source text without immediately rendering it using parse(). parse() returns a Template instance with render() and renderSync() methods.

import { parse } from "liquidscript";

const template = parse("Hello, {{ you }}!");

console.log(template.renderSync({ you: "World" })); // Hello, World!
console.log(template.renderSync({ you: "Liquid" })); // Hello, Liquid!

template.render({ you: "World" }).then(console.log); // Hello, World!
template.render({ you: "Liquid" }).then(console.log); // Hello, Liquid!

Configure

Both parse() and render() are convenience functions that use the default Liquid environment. For all but the simplest cases you'll want to configure your own instance of Environment, then load and render templates from that.

import { Environment, CachingNodeFileSystemLoader } from "liquidscript";

const liquid = new Environment({
  autoEscape: true,
  loader: new CachingNodeFileSystemLoader("./templates")
})

const template = liquid.parse("Hello, {{ you }}!");

// Look for a template called `index.liquid` in the folder `./templates`.
const anotherTemplate = liquid.getTemplate("index.liquid");

What's next?

Read more about configuring your own Liquid environment and loading templates with template loaders.