The liquid substitutions code used by xpm & relatives

Usage no npm install needed!

<script type="module">
  import xpackXpmLiquid from 'https://cdn.skypack.dev/@xpack/xpm-liquid';


npm (scoped) license TS-Standard - Typescript Standard Style Guide


This project implements the Liquid substitutions code used by xpm & relatives.

The project is open-source and hosted on GitHub as xpack/xpm-liquid-ts.


A recent Node.js (>=10.x), since the TypeScript code is compiled to ECMAScript 2018 code.

Easy install

The module is available as @xpack/xpm-liquid from the public repository; use npm to install it inside the module where it is needed:

npm install @xpack/xpm-liquid@latest

The module does not provide any executables, and generally there are no reasons to install it globally.

The development repository is available from the GitHub xpack/xpm-liquid-ts project.

User info

This section is intended for those who want to use this module in their own projects.

The @xpack/xpm-liquid module can be imported in both TypeScript and JavaScript Node.js code.

In TypeScript, use import:

import { XpmLiquid } from '@xpack/xpm-liquid'

In JavaScript, use require():

const { XpmLiquid } = require('@xpack/xpm-liquid')

To use the XpmLiquid class, create an instance of the engine, provide the package.json object, possibly the name of the configuration, and call perform substitutions():

const xpmLiquid = new XpmLiquid(log)
const xpmLiquidMap = xpmLiquid.prepareMap(packagJson, 'Debug')

const var = await xpmLiquid.performSubstitutions(
      '{{ "build" | path_join: configuration.name | to_filename }}',

Available variables

The entire project package.json is available as the package variable:

  • package

All user defined properties (project and configuration) are grouped below the properties variable:

  • properties

If the substitution refers to a certain build configuration, the configuration name and the entire configuration content are available separately below the configuration variable. Configuration properties are added to the properties variable`, possibly overriding project properties.

  • configuration.name
  • configuration.*

Variables based on the Node.js process environment

  • env

Variables based on the Node.js os definitions:

  • os.EOL
  • os.arch (like 'arm', 'arm64', 'ia32', 'x64')
  • os.constants
  • os.cpus
  • os.endianness
  • os.homedir
  • os.hostname
  • os.platform (like 'darwin', 'linux', 'win32')
  • os.release
  • os.tmpdir
  • os.type
  • os.version (available since Node 12)

Variables based on the Node.js path definitions:

  • path.delimiter (; for Windows, : for POSIX)
  • path.sep (\ on Windows, / on POSIX)
  • path.win32.delimiter (;)
  • path.win32.sep (\)
  • path.posix.delimiter (:)
  • path.posix.sep (/)


  • "buildFolderRelativePath": "build{{ path.sep }}{{ configuration.name | to_filename }}"

Custom filters

Filters based on Node.js path functions:

  • path_basename
  • path_dirname
  • path_normalize
  • path_join
  • path_relative
  • path_posix_basename
  • path_posix_dirname
  • path_posix_normalize
  • path_posix_join
  • path_posix_relative
  • path_win32_basename
  • path_win32_dirname
  • path_win32_normalize
  • path_win32_join
  • path_win32_relative

Filters based on Node.js utils functions:

  • util_format

Custom filter to convert generic names to names accepted as file names (letters, digits, dash):

  • to_filename


  • "buildFolderRelativePath": "{{ "build" | path_join: configuration.name | to_filename | downcase }"

Compatibility notices

According to semver requirements, incompatible API changes require higher major numbers.

  • none so far

Maintainer & developer info

This page documents how to use this module in an user application. For developer and maintainer information, see the separate README-DEVELOPER and README-MAINTAINER pages.


The original content is released under the MIT License, with all rights reserved to Liviu Ionescu.