{"id":22760,"library":"vite-plugin-nunjucks","title":"vite-plugin-nunjucks","description":"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.","status":"active","version":"0.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/Jax-p/vite-plugin-nunjucks","tags":["javascript","vite","vite-plugin","nunjucks","typescript"],"install":[{"cmd":"npm install vite-plugin-nunjucks","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-nunjucks","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-nunjucks","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency: requires Vite ^5.0.2","package":"vite","optional":false}],"imports":[{"note":"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.","wrong":"const nunjucks = require('vite-plugin-nunjucks');","symbol":"default (nunjucks plugin function)","correct":"import nunjucks from 'vite-plugin-nunjucks'"},{"note":"Types are exported as type-only exports. Use `import type` to avoid bundling issues.","wrong":"import { VariablesConfig } from 'vite-plugin-nunjucks';","symbol":"Plugin options (VariablesConfig, NunjucksEnvironment)","correct":"import type { VariablesConfig, NunjucksEnvironment } from 'vite-plugin-nunjucks'"},{"note":"Variables must be keyed by entry HTML file name (e.g., 'index.html'). Passing flat variables won't work as expected.","wrong":"export default { plugins: [ nunjucks({ variables: { username: 'John' } }) ] }","symbol":"Nunjucks template include path resolution","correct":"import nunjucks from 'vite-plugin-nunjucks'; export default { plugins: [ nunjucks({ variables: { 'index.html': { username: 'John' } } }) ] }"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport nunjucks from 'vite-plugin-nunjucks';\n\nexport default defineConfig({\n plugins: [\n nunjucks({\n variables: {\n 'index.html': { title: 'My App', username: process.env.USER ?? 'guest' }\n },\n nunjucksEnvironment: {\n filters: {\n uppercase: (val: string) => val.toUpperCase()\n }\n }\n })\n ]\n});\n\n// src/index.html\n{% extends \"src/layout.html\" %}\n{% block content %}\n

Hello {{ username }}

\n{% endblock %}\n\n// src/layout.html\n\nMy App{% block content %}{% endblock %}","lang":"typescript","description":"Shows basic config with per-entry variables and a custom Nunjucks filter, plus template inheritance."},"warnings":[{"fix":"Ensure the variables object has keys like 'index.html', 'about.html', etc.","message":"Variables must be keyed by entry HTML filename, not a flat object. Misconfiguring variables won't throw an error but will silently fail.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Update Vite to 5.x or use previous version of this plugin (if available).","message":"Requires Vite ^5.0.2. Older Vite versions (4.x) are not supported.","severity":"breaking","affected_versions":">=0.2.0"},{"fix":"Use nunjucksEnvironment.filters and nunjucksEnvironment.extensions, not top-level filters/extensions.","message":"Custom filters and extensions must be passed via nunjucksEnvironment option (since v0.1.4). Older configuration style may break.","severity":"gotcha","affected_versions":">=0.1.4"},{"fix":"Use { async: true, filter: yourAsyncFilter } structure.","message":"Async filters use nunjucksFilter property (not nunjucksFilterCallback) as of the current version.","severity":"deprecated","affected_versions":">=0.1.4"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Run `npm install vite-plugin-nunjucks --save-dev` and ensure tsconfig.json includes allowSyntheticDefaultImports or esModuleInterop.","cause":"The package may not be installed, or TypeScript cannot resolve types because it's not a default export with types.","error":"Cannot find module 'vite-plugin-nunjucks' or its corresponding type declarations."},{"fix":"Install Vite ^5.0.2: `npm install vite@^5.0.2 --save-dev`","cause":"Vite is not installed or the version is incompatible (requires ^5.0.2).","error":"Error: Failed to load plugin 'vite-plugin-nunjucks': Cannot find module 'vite'"},{"fix":"Set variables: { 'index.html': { username: 'John' } } instead of variables: { username: 'John' }","cause":"Incorrect variable configuration: variables were passed as flat object instead of keyed by entry file.","error":"Error: Variable 'username' is undefined"},{"fix":"Check template for unmatched {% block %} or {% endblock %} tags. Ensure correct Nunjucks syntax.","cause":"Template syntax error or missing closing tags in Nunjucks template.","error":"Error: Template render error: (unknown path) [Line X, Column Y] expected block end"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}