handlebars-lint

1.0.0 verified Fri May 01 auth: no javascript deprecated

Lint Handlebars templates for missing variables, helpers, block helpers, or partials. Current stable version is 1.0.0. The package takes a template string and a context object with known helpers and variables, then returns an object categorizing any missing references. It differentiates between variables, helpers, block helpers, and partials. There is no active maintenance; the last release was in 2016 and the GitHub repository has been archived. It requires Node >=4 and depends on the `handlebars` package for parsing.

Common errors

error TypeError: Handlebars.compile is not a function ↓

cause Handlebars is not installed or not passed correctly in options.

fix

Install handlebars (npm install handlebars) and pass options.hbs: require('handlebars').

error Cannot read property 'helpers' of undefined ↓

cause The `context` option is missing or not an object with `helpers` property.

fix

Provide a context object like { context: { helpers: {}, variables: {} } }.

error The expression '{{foo}}' is ambiguous; assumed variable. If 'foo' is a helper, add it to the context.helpers. ↓

cause A single word like `{{foo}}` is not found in helpers or variables; defaults to variable.

fix

Add foo to context.helpers if it is a helper, or to context.variables if it is a variable.

Warnings

deprecated Package is deprecated and no longer maintained. Last release 2016. Use ESLint plugin for Handlebars or manual validation. ↓

fix Migrate to eslint-plugin-handlebars or implement custom validation.

gotcha The linter treats expressions without params/hash as variables if not found in helpers or variables. This may misclassify single-word helpers (e.g. {{foo}} where foo is actually a helper without arguments). ↓

fix Explicitly define all helpers and variables in the context object to avoid misclassification.

gotcha Requires passing an optional `Handlebars` instance via `options.hbs`; if not provided, it uses the global `Handlebars` which may not be installed. ↓

fix Ensure Handlebars is installed and optionally pass `hbs: Handlebars` in options.

breaking The `options.context` property must be an object with `helpers` and `variables` (and optionally `partials` and `blockHelpers`). Providing a flat object will throw or produce incorrect results. ↓

fix Use `{ context: { helpers: {}, variables: {} } }` as shown in examples.

Install

npm install handlebars-lint

yarn add handlebars-lint

pnpm add handlebars-lint

Imports

default

wrong

const lint = require('handlebars-lint');

correct

import lint from 'handlebars-lint';

Package is CommonJS, but ESM import works as default export.

lint

wrong

import { lint } from 'handlebars-lint';

correct

const lint = require('handlebars-lint');

The module exports a single function; named import is incorrect.

types

wrong

import { LintResult } from 'handlebars-lint';

correct

import type { LintResult } from 'handlebars-lint';

Type imports are available if using TypeScript with the package's bundled types.

Quickstart

This shows how to lint a simple Handlebars template for missing variables using the default import.

import Handlebars from 'handlebars';
import lint from 'handlebars-lint';

const template = '{{greeting}} {{name}}';
const context = {
  helpers: {},
  variables: { greeting: 'Hello' }
};
const missing = lint(template, { context });
console.log(missing);
// { variables: [ 'name' ], helpers: [], partials: [], blockHelpers: [] }