@xpack/xpm-liquid

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.

Prerequisites

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 and ECMAScript modules, use import:

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

In JavaScript with CommonJS, 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(packageJson, 'Debug')

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

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 variables, 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 (/)

Examples:

• "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
• to_posix_filename
• to_win32_filename

Examples:

• "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.

License

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