Registry / serialization / simple-nunjucks-loader

simple-nunjucks-loader

library3.2.0jsnpmunverified

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.

serialization web-framework

npm install simple-nunjucks-loader

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SIMPLE-NUNJUCKS-LO

simple-nunjucks-loader

serializationjavascriptv3.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default (import loader in webpack config)

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

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

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

template function (default export from .njk file)

✓ import tmpl from './template.njk'; tmpl({ foo: 'bar' })

✗ import { template } from './template.njk' (named import does not exist)

Loader exposes the compiled template as default export; named imports are not available.

TypeScript types

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

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

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

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');

Debug

Known issues

breakingIn 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 %}`.

affects: >=2.0.0

breakingVersion 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.

affects: >=3.0.0

deprecatedES 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.

affects: >=2.0.0 <3.0.0

gotchaIf 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.

affects: >=2.0.0

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

affects: >=2.0.0

gotchaLoader 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.

affects: >=1.0.0

Errors

Common errors & fixes

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

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'] }

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

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: static is not defined (in template)

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.

Upgrade

Version history

3.2.0latest on npm

Audit

Dependencies

nunjucksrequiredRuntime library for rendering compiled templates

webpackrequiredCore bundler; loader runs inside Webpack 5

globoptionalUsed only for dynamic asset resolution; can be omitted if not using {% static %} tag

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/ogonkov/nunjucks-loader ↗

packagehttps://www.npmjs.com/package/simple-nunjucks-loader ↗

homepagehttps://ogonkov.github.io/nunjucks-loader/ ↗