Fumanchu

Browser Support

How to use Fumanchu in the browser and the list of helpers registered in the browser-safe build.

Fumanchu ships a browser-safe build that excludes helpers that depend on Node core modules. The public API (fumanchu, helpers, HelperRegistry) is the same as Node.js; only the registered helper set differs.

Table of Contents

Import the browser build

Use the /browser subpath when you want the browser registry explicitly:

import { fumanchu } from '@jaredwray/fumanchu/browser';

const handlebars = fumanchu();
const template = handlebars.compile('{{uppercase name}}');
console.log(template({ name: 'hello' })); // HELLO

The package also sets the browser export condition on the main entry. Webpack, Vite, esbuild, Rollup, and other browser-aware bundlers pick up the browser build automatically when you import '@jaredwray/fumanchu' from a browser target — no code change required.

Register helpers on an existing Handlebars instance

import { helpers } from '@jaredwray/fumanchu/browser';
import Handlebars from 'handlebars';

helpers({ handlebars: Handlebars });
const template = Handlebars.compile('{{#if (eq foo "bar")}}<p>Foo is bar</p>{{/if}}');
console.log(template({ foo: 'bar' }));

Load from a CDN

You can load the browser build from a CDN such as jsDelivr with no bundler:

<script type="module">
  import { fumanchu } from 'https://cdn.jsdelivr.net/npm/@jaredwray/fumanchu/dist/index.browser.mjs';
  const handlebars = fumanchu();
  document.body.textContent = handlebars.compile('{{uppercase name}}')({ name: 'hello' });
</script>

Helper registry

HelperRegistry in the browser entry is the browser-safe registry. It registers every environment-neutral helper and omits anything that depends on Node core modules.

import { HelperRegistry, handlebars } from '@jaredwray/fumanchu/browser';

const registry = new HelperRegistry();
registry.load(handlebars);

Caching

Template compile caching works the same way as on Node. Pass caching: true, a CacheableMemory instance, or cache options:

import { fumanchu } from '@jaredwray/fumanchu/browser';

const handlebars = fumanchu({ caching: true });
const template = handlebars.compile('{{uppercase name}}');
console.log(template({ name: 'hello' })); // HELLO

Not available in the browser

These helpers need Node APIs (fs, path, the terminal, and related modules) and are not registered in the browser build:

  • The entire fs, path, and logging categories
  • embed from code
  • css and js from html
  • escape, urlResolve, urlParse, and stripProtocol from url

Markdown helpers (md, markdown) are registered. They render inline markdown only — unlike Node, they will not read a file path from disk.

See Node.js Support for the full helper set, including Node-only helpers.

Available helpers

See the category pages for parameters and examples.

Category Name Description
array after Returns all of the items in an array after the specified index.
array before Return all of the items in the collection before the specified count.
array arrayify Cast the given value to an array.
array first Returns the first item, or first n items of an array.
array last Returns the last item, or last n items of an array or string.
array length Returns the length of the given string or array.
array join Join all elements of array into a string, optionally using a given separator.
array forEach Iterates over each item in an array and exposes the current item in the array as context to the inner block.
array inArray Block helper that renders the block if an array has the given value.
array isArray Returns true if value is an es5 array.
array itemAt Returns the item from array at index idx.
array equalsLength Returns true if the length of the given value equals the given length.
array some Block helper that returns the block if the callback returns true for some value in the given array.
array eachIndex Block helper that iterates an array and exposes item and index.
array withAfter Use the items in the array after the specified index as context inside a block.
array withBefore Use the items in the array before the specified index as context inside a block.
array withFirst Use the first item in a collection inside a handlebars block expression.
array withLast Use the last item or n items in an array as context inside a block.
array withGroup Block helper that groups array elements by given group size.
array withSort Block helper that sorts a collection and exposes the sorted collection as context inside the block.
array filter Block helper that filters the given array and renders the block for values that evaluate to true, otherwise the inverse block is returned.
array map Returns a new array, created by calling function on each element of the given array.
array pluck Map over the given object or array or objects and create an array of values from the given prop.
array reverse Reverse the elements in an array, or the characters in a string.
array sort Sort the given array.
array sortBy Sort an array.
array unique Block helper that return an array with all duplicate values removed.
code gist Embed a GitHub Gist using only the id of the Gist.
code jsfiddle Generate the HTML for a jsFiddle iframe with the given options.
collection isEmpty Returns true if the given collection is empty.
collection iterate Block helper that iterates over an array or object.
comparison and Helper that renders the block if all of the given values are truthy.
comparison compare Render a block when a comparison of the first and third arguments returns true.
comparison contains Block helper that renders the block if collection has the given value, otherwise the inverse block is rendered (if specified).
comparison default Returns the first value that is not null or undefined, otherwise returns an empty string.
comparison eq Block helper that renders a block if a is strictly equal to b (using ===).
comparison gt Block helper that renders a block if a is greater than b.
comparison gte Block helper that renders a block if a is greater than or equal to b.
comparison has Block helper that renders a block if value has pattern.
comparison isFalsey Returns true if the given value is falsey.
comparison isTruthy Returns true if the given value is truthy (not falsey).
comparison ifEven Returns true if the given value is an even number.
comparison ifNth Returns true if b is divisible by a (remainder is zero when b is divided by a).
comparison ifOdd Block helper that renders a block if value is an odd number.
comparison is Block helper that renders a block if a is equal to b using loose equality (==).
comparison isnt Block helper that renders a block if a is not equal to b using loose inequality (!=).
comparison lt Block helper that renders a block if a is less than b.
comparison lte Block helper that renders a block if a is less than or equal to b.
comparison neither Block helper that renders a block if neither of the given values are truthy.
comparison not Returns true if val is falsey.
comparison or Block helper that renders a block if any of the given values is truthy.
comparison unlessEq Block helper that returns true unless a is strictly equal to b (using !==).
comparison unlessGt Block helper that returns true unless a is greater than b (equivalent to a <= b).
comparison unlessLt Block helper that returns true unless a is less than b (equivalent to a >= b).
comparison unlessGteq Block helper that returns true unless a is greater than or equal to b (equivalent to a < b).
comparison unlessLteq Block helper that returns true unless a is less than or equal to b (equivalent to a > b).
date year Get the current year as a string.
date date Format a date with support for human-readable date strings, Date objects, timestamps, or defaults to current date.
date moment Legacy alias for {{date}}.
date timestamp Returns the current Unix timestamp in milliseconds.
date now Returns the current date/time with optional formatting.
date fromNow Display relative time from now (e.g., "5 minutes ago", "in 2 hours").
date toNow Opposite of fromNow.
date ago Alias for {{fromNow}}.
date dateAdd Add time to a date.
date dateSubtract Subtract time from a date.
date startOf Get the start of a time period.
date endOf Get the end of a time period.
date isBefore Check if the first date is before the second date.
date isAfter Check if the first date is after the second date.
date isSame Check if two dates are the same, with optional unit precision.
date isBetween Check if a date is between two other dates (inclusive).
date diff Calculate the difference between two dates.
date toISOString Convert a date to ISO 8601 format.
date dateTimezone Format a date in a specific timezone.
date dateLocale Format a date with a specific locale.
html attr Stringify attributes from the options hash into an HTML attribute string.
html sanitize Strip all HTML tags from a string, preserving only the text content.
html ul Block helper for creating unordered lists.
html ol Block helper for creating ordered lists.
html thumbnailImage Generate a <figure> element with a thumbnail image, optional link to full-size image, and optional caption.
i18n i18n Looks up a translation key for the current language.
inflection inflect Returns either the singular or plural inflection of a word based on the given count.
inflection ordinalize Returns an ordinalized number as a string.
markdown md Converts a markdown string to HTML.
markdown markdown Block helper that converts a string of inline markdown to HTML.
match match Returns an array of strings that match the given glob pattern(s).
match isMatch Returns true if a filepath matches the given pattern.
match mm Deprecated alias for match.
math abs Return the magnitude of a.
math add Return the sum of a plus b.
math avg Returns the average of all numbers in the given array.
math ceil Get the Math.ceil() of the given value.
math divide Divide a by b.
math floor Get the Math.floor() of the given value.
math minus Return the difference of a minus b.
math modulo Get the remainder of a division operation.
math multiply Return the product of a times b.
math plus Add a by b.
math random Generate a random number between two values.
math remainder Get the remainder when a is divided by b.
math round Round the given number.
math subtract Return the product of a minus b.
math sum Returns the sum of all numbers in the given array.
math times Multiply number a by number b.
misc frame Block helper for exposing private @ variables on the context.
misc option Return the given value of prop from this.options.
misc noop Block helper that renders the block without taking any arguments.
misc typeOf Get the native type of the given value.
misc withHash Block helper that builds the context for the block from the options hash.
number bytes Format a number to it's equivalent in bytes.
number addCommas Add commas to numbers.
number phoneNumber Convert a string or number to a formatted phone number.
number toAbbr Abbreviate numbers to the given number of precision.
number toExponential Returns a string representing the given number in exponential notation.
number toFixed Formats the given number using fixed-point notation.
number toFloat Convert the given value to a floating-point number.
number toInt Convert the given value to an integer.
number toPrecision Returns a string representing the Number object to the specified precision.
object extend Extend the context with the properties of other objects.
object forIn Block helper that iterates over the properties of an object, exposing each key and value on the context.
object forOwn Block helper that iterates over the own properties of an object, exposing each key and value on the context.
object toPath Take arguments and, if they are string or number, convert them to a dot-delineated object property path.
object get Use property paths (a.b.c) to get a value or nested value from the context.
object getObject Use property paths (a.b.c) to get an object from the context.
object hasOwn Return true if key is an own, enumerable property of the given context object.
object isObject Return true if value is an object.
object JSONparse Parses the given string using JSON.parse.
object JSONstringify Stringify an object using JSON.stringify.
object merge Deeply merge the properties of the given objects with the context object.
object parseJSON Alias for JSONparse.
object pick Pick properties from the context object.
object stringify Alias for JSONstringify.
regex toRegex Convert the given string to a regular expression.
regex test Returns true if the given str matches the given regex.
string append Append the specified suffix to the given string.
string camelcase camelCase the characters in the given string.
string capitalize Capitalize the first word in a sentence.
string capitalizeAll Capitalize all words in a string.
string center Center a string using non-breaking spaces.
string chop Like trim, but removes both extraneous whitespace and non-word characters from the beginning and end of a string.
string dashcase dash-case the characters in string.
string dotcase dot.case the characters in string.
string ellipsis Truncates a string to the specified length, and appends it with an elipsis, ….
string hyphenate Replace spaces in a string with hyphens.
string isString Return true if value is a string.
string lowercase Lowercase all characters in the given string.
string downcase Lowercase all of the characters in the given string.
string occurrences Return the number of occurrences of substring within the given string.
string pascalcase PascalCase the characters in string.
string pathcase path/case the characters in string.
string plusify Replace spaces in the given string with pluses.
string prepend Prepends the given string with the specified prefix.
string remove Remove all occurrences of substring from the given str.
string removeFirst Remove the first occurrence of substring from the given str.
string replace Replace all occurrences of substring a with substring b.
string replaceFirst Replace the first occurrence of substring a with substring b.
string sentence Sentence case the given string.
string snakecase snake_case the characters in the given string.
string trim Removes extraneous whitespace from the beginning and end of a string.
string trimLeft Removes extraneous whitespace from the beginning of a string.
string trimRight Removes extraneous whitespace from the end of a string.
string truncate Truncate a string to the specified length.
string truncateWords Truncate a string to have the specified number of words.
string uppercase Uppercase all of the characters in the given string.
string upcase Uppercase all of the characters in the given string.
string split Split string by the given character.
string startsWith Tests whether a string begins with the given prefix.
string titleize Title case the given string.
string raw Render a block without processing mustache templates inside the block.
url encodeURI Encodes a URI component.
url decodeURI Decode a Uniform Resource Identifier (URI) component.
url url_encode Alias for encodeURI.
url url_decode Alias for decodeURI.
url stripQuerystring Strip the query string from the given url.