Nunjucks Template Testing Utility

Common errors

• Error: The 'views' parameter must be a string or array of strings.

  cause The `views` argument passed to `renderer` is not a string or an array of strings.
  fix Ensure `renderer(views, ...)` receives a valid path string or an array of path strings, e.g., `renderer(['./views'], ...)`.

• Nunjucks Error: template not found: my-template.html

  cause The specified template file does not exist in any of the configured `views` directories.
  fix Verify the template path and ensure it's accessible from one of the directories provided in the `views` array during `renderer` initialization. Check for typos or incorrect relative paths.

• Nunjucks Error: Unknown filter "myCustomFilter"

  cause A custom filter used in a Nunjucks template was not registered with the Nunjucks environment.
  fix Pass an object containing your custom filters to the `filters` parameter of the `renderer` function, e.g., `renderer(views, locales, globals, { myCustomFilter: () => {} })`.

• TypeError: myRenderFunc is not a function

  cause The `renderer` factory function was not called, or its return value (the actual render function) was not correctly assigned to a variable.
  fix Ensure you call `renderer(...)` and assign its result: `const myRenderFunc = renderer(views, locales);`.

Warnings

• breaking Version 3.0.0 of hmpo-nunjucks-test requires Node.js runtime version 24.x. Projects running on older Node.js versions must upgrade their environment to use v3.x.
  Fix: Upgrade your Node.js environment to version 24.x or newer, or stick to hmpo-nunjucks-test v2.x for older Node.js versions.
• gotcha This library has a peer dependency on `hmpo-components`. While npm typically warns, ensure `hmpo-components` is installed in your project, as its globals and filters are often implicitly expected.
  Fix: Install `hmpo-components` in your project: `npm install hmpo-components` or `yarn add hmpo-components`.

Install

• npm install hmpo-nunjucks-test npm
• yarn add hmpo-nunjucks-test yarn
• pnpm add hmpo-nunjucks-test pnpm

Imports

• renderer
  wrong:

  const renderer = require('hmpo-nunjucks-test').renderer;

  correct:

  import { renderer } from 'hmpo-nunjucks-test';

  The primary factory function for creating Nunjucks renderers. While CommonJS is still supported, ESM is preferred in modern Node.js environments.
• hmpoNunjucksTest
  wrong:

  const hmpoNunjucksTest = require('hmpo-nunjucks-test');

  correct:

  import * as hmpoNunjucksTest from 'hmpo-nunjucks-test';

  CommonJS `require` returns an object containing named exports. For ESM, use `import * as` for similar behavior.

Quickstart

This quickstart initializes the Nunjucks renderer with sample view and locale paths, then demonstrates rendering both a full template with context and localization, and a specific Nunjucks component.

const path = require('path');
const { renderer } = require('hmpo-nunjucks-test');
const fs = require('fs');

// Create dummy view and locale files for the example
const viewsDir = path.resolve(__dirname, 'views');
const localeDir = path.resolve(__dirname, 'locale');

fs.mkdirSync(viewsDir, { recursive: true });
fs.mkdirSync(localeDir, { recursive: true });

fs.writeFileSync(path.join(viewsDir, 'exampleTemplate.html'), `
  <h1>Hello, {{ data.name }}!</h1>
  <p>{{ translate('greeting') }}</p>
  {% from 'components/my-component.html' import myComponent %}
  {{ myComponent(param='component-data') }}
`);

fs.writeFileSync(path.join(viewsDir, 'components', 'my-component.html'), `
  {% macro myComponent(param) %}
    <p>This is a component with param: {{ param }}</p>
  {% endmacro %}
`);

fs.writeFileSync(path.join(localeDir, 'en.json'), `
  {
    "greeting": "Welcome to the Nunjucks test!"
  }
`);

// Initialize the Nunjucks renderer
const myRenderFunc = renderer(
    [viewsDir],
    [path.join(localeDir, 'en.json')]
);

// Render a template
const templateOutput = myRenderFunc({
    template: 'exampleTemplate.html',
    translate: true
}, { data: { name: 'World' } });

console.log('--- Template Output ---\n', templateOutput);

// Render a component directly
const componentOutput = myRenderFunc({
    component: 'myComponent',
    params: { param: 'another-component-data' },
    ctx: true
});

console.log('\n--- Component Output ---\n', componentOutput);

// Clean up dummy files (optional for actual usage)
// fs.rmSync(viewsDir, { recursive: true, force: true });
// fs.rmSync(localeDir, { recursive: true, force: true });