Panini

1.7.2 verified Fri May 01 auth: no javascript maintenance

A super tiny flat file compiler for Gulp, version 1.7.2. It compiles HTML pages using layouts, partials, Handlebars helpers, and external data (JSON/YAML). It is not a full static site generator but focuses on assembling flat files from common elements. Key differentiators: simple Gulp integration, Handlebars-based templating, front matter support for per-page layouts, and ability to load data from JSON, YAML, or Node modules. Release cadence is irregular; last release in 2019. It is part of the Foundation UI framework ecosystem.

Common errors

error Error: Layout not found: default ↓

cause Panini expects a layout file named 'default.html' (or .hbs/.handlebars) in the specified layouts folder. If missing, this error occurs.

fix

Create a file named 'default.html' in your layouts folder, or ensure the layouts option points to the correct folder.

error TypeError: Cannot read property 'partials' of undefined ↓

cause This error can occur if the partials folder path is incorrect or does not exist. Panini tries to load partials and fails silently, but accessing the partial may cause this.

fix

Verify that the partials folder exists and is correctly specified in the options. Ensure files inside have .html, .hbs, or .handlebars extension.

error Error: Failed to load data file: unexpected token ↓

cause Panini uses js-yaml to parse YAML files. An invalid YAML syntax (e.g., indentation errors) will cause this error.

fix

Validate your YAML files using a YAML linter. Ensure proper indentation and syntax.

Warnings

breaking Upgraded from Handlebars 3 to 4 in v1.3.0. Your existing templates will work fine overall, but note that Handlebars 4 changed the execution context for raw blocks (e.g., `{{{{raw}}}}`), which may affect custom helpers that rely on raw blocks. ↓

fix Review any custom raw block usage; ensure they are compatible with Handlebars 4's context.

deprecated Panini's dependency `marked` (for markdown helper) was updated to address CVE-2017-17461 in v1.6.2. If you use the markdown helper, ensure you are on v1.6.2 or later. ↓

fix Upgrade to panini v1.6.2 or later.

gotcha Panini.load() is not available in recent versions; use panini.refresh() instead to reload layouts, partials, helpers, and data. ↓

fix Replace calls to panini.load() with panini.refresh().

Install

npm install panini

yarn add panini

pnpm add panini

Imports

panini
wrong
```
const panini = require('panini');
```
correct
```
import panini from 'panini';
```
Panini is a CommonJS module and does not provide ESM exports. Using require() is correct; there is no default import in ESM style.
panini.refresh
wrong
```
import { refresh } from 'panini';
```
correct
```
const panini = require('panini');
panini.refresh();
```
refresh() is a method on the main panini object, not a named export. Use require('panini') and call panini.refresh().
Panini (constructor)
wrong
```
const { Panini } = require('panini');
```
correct
```
const Panini = require('panini');
const instance = new Panini(options);
```
The module exports a constructor function directly, not a named export. Use require() to get the constructor.

Quickstart

Shows a basic Gulp task using Panini to compile HTML pages with layouts, partials, helpers, data, and a watch that refreshes Panini on changes.

const gulp = require('gulp');
const panini = require('panini');

gulp.task('build', function() {
  return gulp.src('src/pages/**/*.html')
    .pipe(panini({
      root: 'src/pages/',
      layouts: 'src/layouts/',
      partials: 'src/partials/',
      helpers: 'src/helpers/',
      data: 'src/data/',
      pageLayouts: {
        'blog': 'blog'
      }
    }))
    .pipe(gulp.dest('dist'));
});

gulp.watch(['src/{layouts,partials,helpers,data}/**/*'], function() {
  panini.refresh();
});