{"id":15335,"library":"hmpo-nunjucks-test","title":"Nunjucks Template Testing Utility","description":"hmpo-nunjucks-test is a specialized JavaScript library designed for testing Nunjucks templates, including robust support for localization and dynamic rendering. It is currently stable at version 3.0.0, which mandates Node.js v24.x for execution. While there isn't a strict release cadence, updates appear to be made on an as-needed basis, often involving dependency updates and Node runtime bumps. Its core functionality revolves around a `renderer` factory function that sets up a Nunjucks environment, allowing developers to create a render function capable of processing templates, raw strings, or components/macros. A key differentiator is its integrated support for `hmpo-components` globals and filters, and its focus on robust localization testing, making it particularly useful within the HMPO ecosystem for ensuring UI consistency and translation accuracy. It provides granular control over the rendering context, translation flags, and component parameters, addressing common testing challenges in Nunjucks-based applications.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/HMPO/hmpo-nunjucks-test","tags":["javascript"],"install":[{"cmd":"npm install hmpo-nunjucks-test","lang":"bash","label":"npm"},{"cmd":"yarn add hmpo-nunjucks-test","lang":"bash","label":"yarn"},{"cmd":"pnpm add hmpo-nunjucks-test","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides default Nunjucks globals and filters, essential for typical usage.","package":"hmpo-components","optional":false}],"imports":[{"note":"The primary factory function for creating Nunjucks renderers. While CommonJS is still supported, ESM is preferred in modern Node.js environments.","wrong":"const renderer = require('hmpo-nunjucks-test').renderer;","symbol":"renderer","correct":"import { renderer } from 'hmpo-nunjucks-test';"},{"note":"CommonJS `require` returns an object containing named exports. For ESM, use `import * as` for similar behavior.","wrong":"const hmpoNunjucksTest = require('hmpo-nunjucks-test');","symbol":"hmpoNunjucksTest","correct":"import * as hmpoNunjucksTest from 'hmpo-nunjucks-test';"}],"quickstart":{"code":"const path = require('path');\nconst { renderer } = require('hmpo-nunjucks-test');\nconst fs = require('fs');\n\n// Create dummy view and locale files for the example\nconst viewsDir = path.resolve(__dirname, 'views');\nconst localeDir = path.resolve(__dirname, 'locale');\n\nfs.mkdirSync(viewsDir, { recursive: true });\nfs.mkdirSync(localeDir, { recursive: true });\n\nfs.writeFileSync(path.join(viewsDir, 'exampleTemplate.html'), `\n  <h1>Hello, {{ data.name }}!</h1>\n  <p>{{ translate('greeting') }}</p>\n  {% from 'components/my-component.html' import myComponent %}\n  {{ myComponent(param='component-data') }}\n`);\n\nfs.writeFileSync(path.join(viewsDir, 'components', 'my-component.html'), `\n  {% macro myComponent(param) %}\n    <p>This is a component with param: {{ param }}</p>\n  {% endmacro %}\n`);\n\nfs.writeFileSync(path.join(localeDir, 'en.json'), `\n  {\n    \"greeting\": \"Welcome to the Nunjucks test!\"\n  }\n`);\n\n// Initialize the Nunjucks renderer\nconst myRenderFunc = renderer(\n    [viewsDir],\n    [path.join(localeDir, 'en.json')]\n);\n\n// Render a template\nconst templateOutput = myRenderFunc({\n    template: 'exampleTemplate.html',\n    translate: true\n}, { data: { name: 'World' } });\n\nconsole.log('--- Template Output ---\\n', templateOutput);\n\n// Render a component directly\nconst componentOutput = myRenderFunc({\n    component: 'myComponent',\n    params: { param: 'another-component-data' },\n    ctx: true\n});\n\nconsole.log('\\n--- Component Output ---\\n', componentOutput);\n\n// Clean up dummy files (optional for actual usage)\n// fs.rmSync(viewsDir, { recursive: true, force: true });\n// fs.rmSync(localeDir, { recursive: true, force: true });\n","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Install `hmpo-components` in your project: `npm install hmpo-components` or `yarn add hmpo-components`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure `renderer(views, ...)` receives a valid path string or an array of path strings, e.g., `renderer(['./views'], ...)`.","cause":"The `views` argument passed to `renderer` is not a string or an array of strings.","error":"Error: The 'views' parameter must be a string or array of strings."},{"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.","cause":"The specified template file does not exist in any of the configured `views` directories.","error":"Nunjucks Error: template not found: my-template.html"},{"fix":"Pass an object containing your custom filters to the `filters` parameter of the `renderer` function, e.g., `renderer(views, locales, globals, { myCustomFilter: () => {} })`.","cause":"A custom filter used in a Nunjucks template was not registered with the Nunjucks environment.","error":"Nunjucks Error: Unknown filter \"myCustomFilter\""},{"fix":"Ensure you call `renderer(...)` and assign its result: `const myRenderFunc = renderer(views, locales);`.","cause":"The `renderer` factory function was not called, or its return value (the actual render function) was not correctly assigned to a variable.","error":"TypeError: myRenderFunc is not a function"}],"ecosystem":"npm"}