@xpack/xpm-liquid NPM

@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.