Skip to main content

Getting Started

LiquidScript is a JavaScript and TypeScript engine for Liquid, the safe, customer-facing template language for flexible web apps.

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

Install​

Node.js​

Install LiquidScript using your preferred project manager:

npm install --save liquidscript

And import the module:

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

Or, without the liquid namespace:

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

Browser​

Download and include LiquidScript in a script tag:

<script src="path/to/liquidscript.iife.bundle.min.js"></script>
<script>
  const template = liquidscript.Template.from("Hello, {{ you }}!");
  template.render({ you: "World" }).then(console.log);
</script>

Or, using a CDN:

<script
  src="https://cdn.jsdelivr.net/npm/liquidscript@1.3.0/dist/liquidscript.iife.bundle.min.js"
  integrity="sha256-HzMfVtmaQXB2y2rp9sGVLrcHK8xMFzkX2r83OYCaUhA="
  crossorigin="anonymous"
></script>
<script>
  const template = liquidscript.Template.from("Hello, {{ you }}!");
  template.render({ you: "World" }).then(console.log);
</script>

Render​

Render a template string by creating a Template and calling its render() or renderSync() methods.

import { Template } from "liquidscript";

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

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

import { Template } from "liquidscript";

const template = Template.fromString(`
{%- for person in people -%}
  Hello, {{ person.name }}!
{% endfor -%}
`);

const data = {
  people: [{ name: "John" }, { name: "Sally" }],
};

console.log(template.renderSync(data));
// Hello, John
// Hello, Sally

The optional second argument to Template.fromString() is an object containing global render context variables. These will be pinned to the resulting template and included automatically every time you call render() or renderSync().

Configure​

You can pass configuration options as the third argument to Template.fromString(). This example enables automatic HTML escaping and will throw an error at render time if a template attempts to use an undefined variable. See EnvironmentOptions for all available options.

import { Template, StrictUndefined } from "liquidscript";

const template = Template.fromString(
  "Hello, {{ you }}!",
  {},
  {
    autoEscape: true,
    undefinedFactory: StrictUndefined.from,
  }
);

Environment​

While Template.fromString() can be convenient, most applications will want to configure a single Environment, then load and render templates from it. This is usually more efficient than using Template directly.

import {
  Environment,
  NodeFileSystemLoader,
  StrictUndefined,
} from "liquidscript";

const env = new Environment({
  autoEscape: true,
  loader: new NodeFileSystemLoader("./templates/"),
  undefinedFactory: StrictUndefined.from,
});

const template = env.fromString("Hello, {{ you }}!");

Notice that Environment accepts a loader option, whereas Template.fromString() does not.