vite-plugin-nunjucks

0.2.0 verified Mon Apr 27 auth: no javascript

Vite plugin for the Nunjucks templating engine (by Mozilla). Version 0.2.0 is the latest stable release. It allows Vite projects to preprocess HTML files with Nunjucks templates, supporting layouts, includes, variables, custom filters, and extensions. Unlike directly using Nunjucks with Vite's HTML processing, this plugin integrates seamlessly with Vite's build and dev server, providing HMR-friendly template processing. It ships TypeScript types and requires Vite ^5.0.2 as a peer dependency.

Common errors

error Cannot find module 'vite-plugin-nunjucks' or its corresponding type declarations. ↓

cause The package may not be installed, or TypeScript cannot resolve types because it's not a default export with types.

fix

Run npm install vite-plugin-nunjucks --save-dev and ensure tsconfig.json includes allowSyntheticDefaultImports or esModuleInterop.

error Error: Failed to load plugin 'vite-plugin-nunjucks': Cannot find module 'vite' ↓

cause Vite is not installed or the version is incompatible (requires ^5.0.2).

fix

Install Vite ^5.0.2: npm install vite@^5.0.2 --save-dev

error Error: Variable 'username' is undefined ↓

cause Incorrect variable configuration: variables were passed as flat object instead of keyed by entry file.

fix

Set variables: { 'index.html': { username: 'John' } } instead of variables: { username: 'John' }

error Error: Template render error: (unknown path) [Line X, Column Y] expected block end ↓

cause Template syntax error or missing closing tags in Nunjucks template.

fix

Check template for unmatched {% block %} or {% endblock %} tags. Ensure correct Nunjucks syntax.

Warnings

gotcha Variables must be keyed by entry HTML filename, not a flat object. Misconfiguring variables won't throw an error but will silently fail. ↓

fix Ensure the variables object has keys like 'index.html', 'about.html', etc.

breaking Requires Vite ^5.0.2. Older Vite versions (4.x) are not supported. ↓

fix Update Vite to 5.x or use previous version of this plugin (if available).

gotcha Custom filters and extensions must be passed via nunjucksEnvironment option (since v0.1.4). Older configuration style may break. ↓

fix Use nunjucksEnvironment.filters and nunjucksEnvironment.extensions, not top-level filters/extensions.

deprecated Async filters use nunjucksFilter property (not nunjucksFilterCallback) as of the current version. ↓

fix Use { async: true, filter: yourAsyncFilter } structure.

Install

npm install vite-plugin-nunjucks

yarn add vite-plugin-nunjucks

pnpm add vite-plugin-nunjucks

Imports

default (nunjucks plugin function)
wrong
```
const nunjucks = require('vite-plugin-nunjucks');
```
correct
```
import nunjucks from '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)
wrong
```
import { VariablesConfig } from 'vite-plugin-nunjucks';
```
correct
```
import type { VariablesConfig, NunjucksEnvironment } from 'vite-plugin-nunjucks'
```
Types are exported as type-only exports. Use `import type` to avoid bundling issues.

Nunjucks template include path resolution

wrong

export default { plugins: [ nunjucks({ variables: { username: 'John' } }) ] }

correct

import nunjucks from 'vite-plugin-nunjucks'; export default { plugins: [ nunjucks({ variables: { 'index.html': { username: 'John' } } }) ] }

Variables must be keyed by entry HTML file name (e.g., 'index.html'). Passing flat variables won't work as expected.

Quickstart

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>