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
muslnode 18–223 runs
build_error
glibcnode 18–223 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
default (nunjucks plugin function)
✓ import nunjucks from 'vite-plugin-nunjucks'
✗ const nunjucks = require('vite-plugin-nunjucks');
This is a Vite plugin, so ESM import is required when using Vite's ESM config. CommonJS require may work in older Node versions but is not recommended.
Plugin options (VariablesConfig, NunjucksEnvironment)
✓ import type { VariablesConfig, NunjucksEnvironment } from 'vite-plugin-nunjucks'
✗ import { VariablesConfig } from 'vite-plugin-nunjucks';
Types are exported as type-only exports. Use `import type` to avoid bundling issues.
Nunjucks template include path resolution
✓ import nunjucks from 'vite-plugin-nunjucks'; export default { plugins: [ nunjucks({ variables: { 'index.html': { username: 'John' } } }) ] }
✗ export default { plugins: [ nunjucks({ variables: { username: 'John' } }) ] }
Variables must be keyed by entry HTML file name (e.g., 'index.html'). Passing flat variables won't work as expected.
Shows basic config with per-entry variables and a custom Nunjucks filter, plus template inheritance.
// vite.config.ts
import { defineConfig } from 'vite';
import nunjucks from 'vite-plugin-nunjucks';
export default defineConfig({
plugins: [
nunjucks({
variables: {
'index.html': { title: 'My App', username: process.env.USER ?? 'guest' }
},
nunjucksEnvironment: {
filters: {
uppercase: (val: string) => val.toUpperCase()
}
}
})
]
});
// src/index.html
{% extends "src/layout.html" %}
{% block content %}
<h1>Hello {{ username }}</h1>
<p>{{ title | uppercase }}</p>
{% endblock %}
// src/layout.html
<!DOCTYPE html>
<html><head><title>My App</title></head><body>{% block content %}{% endblock %}</body></html>
Errors
Common errors & fixes
Cannot find module 'vite-plugin-nunjucks' or its corresponding type declarations.
The package may not be installed, or TypeScript cannot resolve types because it's not a default export with types.
fixRun `npm install vite-plugin-nunjucks --save-dev` and ensure tsconfig.json includes allowSyntheticDefaultImports or esModuleInterop.
Error: Failed to load plugin 'vite-plugin-nunjucks': Cannot find module 'vite'
Vite is not installed or the version is incompatible (requires ^5.0.2).
fixInstall Vite ^5.0.2: `npm install vite@^5.0.2 --save-dev`
Error: Variable 'username' is undefined
Incorrect variable configuration: variables were passed as flat object instead of keyed by entry file.
fixSet variables: { 'index.html': { username: 'John' } } instead of variables: { username: 'John' } Error: Template render error: (unknown path) [Line X, Column Y] expected block end
Template syntax error or missing closing tags in Nunjucks template.
fixCheck template for unmatched {% block %} or {% endblock %} tags. Ensure correct Nunjucks syntax. Audit
Dependencies
viterequiredpeer dependency: requires Vite ^5.0.2