simple-nunjucks-loader

3.2.0 verified Sat Apr 25 auth: no javascript

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.

Common errors

error Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type. ↓

cause Webpack is not configured to handle .njk files (missing rule for simple-nunjucks-loader).

fix

Add rule in webpack.config.js: { test: /\.njk$/, use: ['simple-nunjucks-loader'] }

error Template not found: "path/to/template.njk" (included from "other.njk") ↓

cause The loader cannot resolve the path to the included template because `searchPaths` option is not set or incorrect.

fix

Set the searchPaths option in the loader config to the directory containing your templates: { loader: 'simple-nunjucks-loader', options: { searchPaths: ['./src/templates'] } }

error Error: static is not defined (in template) ↓

cause Using the global function `static()` which was removed in v2.0.0; must use `{% static %}` tag instead.

fix

Replace {{ static('path') }} with {% static 'path' %} in your Nunjucks template.

Warnings

breaking In v2.0.0, the global function `static` was replaced with a `{% static %}` tag. Old syntax `{{ static('image.png') }}` no longer works. ↓

fix Replace `{{ static('path') }}` with `{% static 'path' %}` and `{% set var = static('path') %}` with `{% static 'path' as var %}`.

breaking Version 3.0.0 drops Webpack 4 support; requires Webpack 5 or later. ↓

fix Upgrade to Webpack 5, or use simple-nunjucks-loader@2.x for Webpack 4.

deprecated ES modules syntax for filters/extensions may cause issues (documented in v2.0.2). ↓

fix Use CommonJS module syntax for filter and extension files, or upgrade to v3+ where this is partly mitigated.

gotcha If you don't use dynamic assets via {% static %} tag, omitting the optional `glob` dependency can reduce bundle size. ↓

fix Install with `npm install --no-optional simple-nunjucks-loader` to skip glob dependency.

gotcha Templates that use {% static %} or async filters/extensions will return a Promise instead of a string, even if the template itself is synchronous. ↓

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()`.

gotcha Loader options like `watch`, `noCache`, `web`, and `express` from Nunjucks are not supported and will be ignored. ↓

fix Avoid passing unsupported options to the loader; only pass valid Nunjucks `Environment` options like `jinjaCompat`, `searchPaths`, `assetsPath`, etc.

Install

npm install simple-nunjucks-loader

yarn add simple-nunjucks-loader

pnpm add simple-nunjucks-loader

Imports

default (import loader in webpack config)

wrong

Attempting to import simple-nunjucks-loader directly in JS as module: import 'simple-nunjucks-loader'

correct

Use in webpack rules: { test: /\.njk$/, use: ['simple-nunjucks-loader'] }

The loader is used only in Webpack configuration, never imported in application code.

template function (default export from .njk file)
wrong
```
import { template } from './template.njk'  (named import does not exist)
```
correct
```
import tmpl from './template.njk'; tmpl({ foo: 'bar' })
```
Loader exposes the compiled template as default export; named imports are not available.

TypeScript types

wrong

import type { NunjucksTemplate } from 'simple-nunjucks-loader' (no type exports)

correct

// No built-in types; define custom .d.ts: declare module '*.njk' { const tmpl: (ctx: Record<string, any>) => string | Promise<string>; export default tmpl; }

Loader does not ship TypeScript types; users must create their own module declarations for .njk files.

Quickstart

Shows basic Webpack setup with simple-nunjucks-loader and html-webpack-plugin.

// webpack.config.js
const HtmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
  module: {
    rules: [
      {
        test: /\.njk$/,
        use: ['simple-nunjucks-loader']
      }
    ]
  },
  plugins: [
    new HtmlWebpackPlugin({
      template: './src/index.njk',
      filename: 'index.html'
    })
  ]
};

// src/index.njk
<!DOCTYPE html>
<html>
<head><title>{{ title }}</title></head>
<body>
<h1>Hello, {{ name }}!</h1>
</body>
</html>

// src/index.js
import './index.njk'; // Used via HtmlWebpackPlugin, not needed in JS
console.log('Template loaded');