{"id":20550,"library":"simple-nunjucks-loader","title":"simple-nunjucks-loader","description":"A Webpack 5 loader that precompiles Nunjucks templates and integrates with html-webpack-plugin. It parses template AST to automatically resolve imports, filters, and extensions, avoiding the default Nunjucks precompilation global. Features a custom {% static %} tag for async asset handling with HMR support. Current stable version is 3.2.0. Maintained by the community with moderate release cadence (major versions for Webpack upgrades). Key differentiators: full compatibility with Webpack 5, dynamic asset resolution, and zero global pollution.","status":"active","version":"3.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/ogonkov/nunjucks-loader","tags":["javascript","webpack","loader","nunjucks","template","html-webpack-plugin"],"install":[{"cmd":"npm install simple-nunjucks-loader","lang":"bash","label":"npm"},{"cmd":"yarn add simple-nunjucks-loader","lang":"bash","label":"yarn"},{"cmd":"pnpm add simple-nunjucks-loader","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime library for rendering compiled templates","package":"nunjucks","optional":false},{"reason":"Core bundler; loader runs inside Webpack 5","package":"webpack","optional":false},{"reason":"Used only for dynamic asset resolution; can be omitted if not using {% static %} tag","package":"glob","optional":true}],"imports":[{"note":"The loader is used only in Webpack configuration, never imported in application code.","wrong":"Attempting to import simple-nunjucks-loader directly in JS as module: import 'simple-nunjucks-loader'","symbol":"default (import loader in webpack config)","correct":"Use in webpack rules: { test: /\\.njk$/, use: ['simple-nunjucks-loader'] }"},{"note":"Loader exposes the compiled template as default export; named imports are not available.","wrong":"import { template } from './template.njk' (named import does not exist)","symbol":"template function (default export from .njk file)","correct":"import tmpl from './template.njk'; tmpl({ foo: 'bar' })"},{"note":"Loader does not ship TypeScript types; users must create their own module declarations for .njk files.","wrong":"import type { NunjucksTemplate } from 'simple-nunjucks-loader' (no type exports)","symbol":"TypeScript types","correct":"// No built-in types; define custom .d.ts: declare module '*.njk' { const tmpl: (ctx: Record) => string | Promise; export default tmpl; }"}],"quickstart":{"code":"// webpack.config.js\nconst HtmlWebpackPlugin = require('html-webpack-plugin');\n\nmodule.exports = {\n module: {\n rules: [\n {\n test: /\\.njk$/,\n use: ['simple-nunjucks-loader']\n }\n ]\n },\n plugins: [\n new HtmlWebpackPlugin({\n template: './src/index.njk',\n filename: 'index.html'\n })\n ]\n};\n\n// src/index.njk\n\n\n{{ title }}\n\n

Hello, {{ name }}!

\n\n\n\n// src/index.js\nimport './index.njk'; // Used via HtmlWebpackPlugin, not needed in JS\nconsole.log('Template loaded');","lang":"javascript","description":"Shows basic Webpack setup with simple-nunjucks-loader and html-webpack-plugin."},"warnings":[{"fix":"Replace `{{ static('path') }}` with `{% static 'path' %}` and `{% set var = static('path') %}` with `{% static 'path' as var %}`.","message":"In v2.0.0, the global function `static` was replaced with a `{% static %}` tag. Old syntax `{{ static('image.png') }}` no longer works.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade to Webpack 5, or use simple-nunjucks-loader@2.x for Webpack 4.","message":"Version 3.0.0 drops Webpack 4 support; requires Webpack 5 or later.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Use CommonJS module syntax for filter and extension files, or upgrade to v3+ where this is partly mitigated.","message":"ES modules syntax for filters/extensions may cause issues (documented in v2.0.2).","severity":"deprecated","affected_versions":">=2.0.0 <3.0.0"},{"fix":"Install with `npm install --no-optional simple-nunjucks-loader` to skip glob dependency.","message":"If you don't use dynamic assets via {% static %} tag, omitting the optional `glob` dependency can reduce bundle size.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Always check if the return value is a Promise when using dynamic assets or async features: `const result = await tmpl(ctx)` or use `.then()`.","message":"Templates that use {% static %} or async filters/extensions will return a Promise instead of a string, even if the template itself is synchronous.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Avoid passing unsupported options to the loader; only pass valid Nunjucks `Environment` options like `jinjaCompat`, `searchPaths`, `assetsPath`, etc.","message":"Loader options like `watch`, `noCache`, `web`, and `express` from Nunjucks are not supported and will be ignored.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Add rule in webpack.config.js: { test: /\\.njk$/, use: ['simple-nunjucks-loader'] }","cause":"Webpack is not configured to handle .njk files (missing rule for simple-nunjucks-loader).","error":"Module parse failed: Unexpected token (1:0)\nYou may need an appropriate loader to handle this file type."},{"fix":"Set the `searchPaths` option in the loader config to the directory containing your templates: { loader: 'simple-nunjucks-loader', options: { searchPaths: ['./src/templates'] } }","cause":"The loader cannot resolve the path to the included template because `searchPaths` option is not set or incorrect.","error":"Template not found: \"path/to/template.njk\" (included from \"other.njk\")"},{"fix":"Replace `{{ static('path') }}` with `{% static 'path' %}` in your Nunjucks template.","cause":"Using the global function `static()` which was removed in v2.0.0; must use `{% static %}` tag instead.","error":"Error: static is not defined (in template)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}