Technical reference

@brightspot/styleguide provides the styleguide-bundle CLI, a local development server, and the Handlebars rendering pipeline that renders JSON fixtures through Handlebars templates using a Brightspot-specific helper set.

Dependencies

@brightspot/styleguide depends on:

• handlebars for template compilation and rendering.
• chance for generating placeholder data during substitution.
• lodash and traverse for data manipulation and JSON tree walking.
• java-props for loading .properties files used by the format helper.
• messageformat for ICU message formatting in format.
• express for the local development server.
• archiver for bundle zip creation.
• puppeteer / puppeteer-cluster for screenshot generation in styleguide-bundle.

Installation

Add the package to a project with yarn or npm:

1
yarn add --dev @brightspot/styleguide

API reference

styleguide-bundle CLI

@brightspot/styleguide installs a styleguide-bundle executable that packages a styleguide project into a zip:

Flag	Description
-r, --root-dir	Directory containing the styleguide project files (_config.json, templates, JSON fixtures). Defaults to styleguide.
-b, --build-dir	Directory containing the compiled front-end assets to include in the bundle. Required.
-o, --output-file	Path to write the output zip. Required.
-s	Skip generating Puppeteer screenshots of each style and template.
-g, --generate-html	Pre-render each JSON fixture to a static HTML file and include it in the zip.
-c, --puppeteer-cluster-options-file	Path to a JSON file of custom puppeteer-cluster options.
-p, --puppeteer-options-file	Path to a JSON file of custom Puppeteer options.

note

The --no-screenshots long form for -s doesn't currently work—it throws Unknown argument: screenshots under the CLI's strict argument parsing, because yargs' built-in --no--prefix negation intercepts it before the alias resolves. styleguide-bundle --help still lists -s, --no-screenshots together, since yargs prints declared aliases regardless. Use -s until this is fixed.

The local development server (used during template development) serves the styleguide UI and, for any requested HTML path, resolves and renders the matching JSON fixture on the fly.

Handlebars helpers

Every helper below is available in .hbs templates in a styleguide project.

Helper	Description
eq, ne, lt, le, gt, ge	Comparison helpers. Usable as block helpers ({{#eq a b}}...{{/eq}}) or inline with then/otherwise hash arguments.
fallback	Returns the first argument that is not null or undefined.
and, or, not	Boolean logic helpers, usable as block or inline helpers the same way as the comparison helpers.
add, subtract, multiply, divide, remainder	Arithmetic helpers.
set, get	set is a block helper that assigns shared key/value pairs for the duration of the block; get reads a value set by an enclosing set.
resize	Looks up a named crop from a field's resolved image sizes (see Configuration) and renders the block against that resized image.
cycle	Round-robins through a fixed list of positional values by iteration index. Without repeatLast, the whole list repeats in order. With a repeatLast count, the first pass through the list still returns each value in order; every iteration after that cycles only through the last repeatLast values (clamped to the list length) instead of restarting the full list.
partition	Splits an array into fixed-size chunks and iterates over the chunks, similar to {{#each}}.
cdn	Passes a path through unchanged; a theming hook for projects that rewrite asset paths.
extraAttributes	Renders a root-level extraAttributes map as an escaped HTML attribute string.
jsonObject	Renders root.jsonObject as a JSON string when called with no argument, or the passed value when one is given. Returns a SafeString, so the JSON is emitted unescaped.
truncate	Truncates text to a word or character count, with an optional suffix.
escapeHtml	Escapes a string for safe inclusion as text.
format	Looks up an internationalized message from the project's .properties files and formats it with messageformat. Throws on a missing key.
include	Renders a named partial template, merging the current context with any hash arguments.
render	Renders a field's value using the same rules the CMS uses. See below.
styled	Toggles a BEM nesting flag around its block, letting a nested render call know it is inside a styled wrapper.
styledTemplate	Renders its block if the given template file matches the current style override set by render (or if default=true is passed), otherwise renders the inverse block.

render

{{render <field>}} and {{render <field> "<ViewClassName>"}} render a field's value:

• If the field's value is falsy, render outputs nothing.
• If the value is a single-element array, render unwraps it automatically. For arrays with more than one element, render logs a console warning and falls back to concatenating each element's own rendered output; use {{#each array}}{{render this}}{{/each}} instead for clearer results.
• If the value is an object with a nested view (it has a _template), render recurses into that nested view's own template and wraps the result as raw HTML.
  • Any hash pair passed to render maps a base template path to a style override path, for example {{render this [/page/list/PageList.hbs]="/page/list/PageListStandardD.hbs"}}: if the object's own _template matches the hash key, render substitutes the hash value as _styledTemplate before recursing. The styledTemplate helper checks that value to decide which block to render.
• If the value is a plain string or other primitive:
  • Passing a second, positional argument—a Brightspot View class name, for example {{render description "...RichTextArticleBodyViewBodyField"}}—tells render that the CMS would parse this value as a SafeString, so it outputs the value as raw, unescaped HTML.
  • Without that second argument, render outputs the value as plain text, which Handlebars escapes normally.

Because the second positional argument to render is always a view class name and never a hash pair, checking that a string was passed there is enough to detect this case—there is no need to check the class name's spelling. Values that come from a fixture's {{html(...)}} or {{paragraphs(...)}} substitution (see Configuration) already arrive as a SafeString and are output as raw HTML regardless of whether a view argument is passed.

note

Passing the view-class-name argument disables HTML escaping for that value. Only pass it for fields the CMS itself would render as a SafeString (rich text and similar HTML-producing fields)—the argument exists to reproduce CMS escaping behavior, not to force raw HTML for arbitrary fields. For a plain-text field with no markup the escaped and unescaped output are identical, but passing the argument speculatively on a field that later receives markup would let that markup through unescaped.

Configuration

A styleguide project's root directory (the CLI's --root-dir, styleguide by default) must contain a _config.json file, validated against the following fields:

Field	Description
name, version	Project name and version. If omitted, fall back to the nearest package.json found by walking up from the current working directory (not --root-dir), or to the directory name and unversioned if none is found.
colorPalette	Named colors available to templates and the styleguide UI.
styles	The project's styles, each with an example fixture, one or more templates, and optional per-style fields.
themeFields	Theme-wide fields available across all styles.
imageSizes	Named image size and crop definitions used to resolve _image placeholders and the resize helper.
imageProvider	Optional identifier for the image provider used to resolve image URLs.
navigation	The styleguide UI's navigation structure, grouping styles into named pages.
variables	Theme variables available to fixtures through the var() substitution method.
randomSeed	Optional seed for the placeholder-data generator, for reproducible fixture output.
staticFiles	Optional glob patterns for additional files to copy into a bundle.
disableInspector	Optional. When true, disables the inspector overlay entirely: it skips the comment injection the overlay reads from, and skips the AST rewrite during template compilation that annotates templates for it in the first place.

A project can also define _helpers.js in its root directory: raw JavaScript, evaluated against the project's Handlebars instance, for registering additional custom helpers alongside the built-in set. It executes with full Node privileges at bundle and serve time, and is bundled into the delivery zip.

Fixture substitution

JSON fixture files support embedded {{methodName(...)}} expressions inside string values, evaluated before Handlebars rendering. Common methods include date(), name(), number(), words(), sentences(), paragraphs(), var() (reads a value from variables in _config.json), and html(...), which wraps its argument as a SafeString so it renders as raw HTML. Fixtures also support _include (pulling in another fixture file, optionally selecting a random or keyed entry from an array) and _template/_wrapper (nesting a fixture's data inside a parent fixture).