vite-plugin-nunjucks


Vite plugin for Nunjucks.

Supports:
📂 - Templates and layouts 🔗
📃 - Variables for each entry point (HTML) and global scope
🎠 - Custom filters 🔗 and extensions 🔗

Install

Yarn
``
yarn add vite-plugin-nunjucks -D
`
or npm
`
npm i vite-plugin-nunjucks --save-dev
`

Usage

$3

Use plugin in your Vite config (vite.config.ts)
`JavaScript
import nunjucks from 'vite-plugin-nunjucks'

export default {
plugins: [
nunjucks(),
]
}
`

$3

Input (src/index.html):
`html
{% extends "src/html/layout.html" %}
{% include "src/html/hello.html" %}

{% block content %}
{% if username %}
Username: {{ username }}
{% else %}
Variable username is missing
{% endif %}
{% endblock %}
`
Template (src/html/layout.html):
`html




{% block content %}
{% endblock %}


`
Template (src/html/hello.html):
`html

Hello world!

`
Vite config (vite.config.ts)
`JavaScript
import nunjucks from 'vite-plugin-nunjucks'

export default {
plugins: [
nunjucks({ variables: { 'index.html': { username: 'John' }}} ),
]
}
`
Output (dist/index.html)
`html

Hello world!

Username: John


`

Environment

Since v0.1.4 you can pass custom filters and extensions to the environment.
Config example:
`JavaScript
import nunjucks from 'vite-plugin-nunjucks'

export default {
plugins: [
nunjucks({
nunjucksEnvironment: {
filters: {someFilter: someFilter},
extensions: {someExtension: SomeExtension}
}
}),
]
}
`
Filter should look like this _(for more info check the Nunjucks documentation)_
`JavaScript
const someFilter = (val) => {
// ... some logic
return 'My modified filter content';
}
`
and extension like this:
`JavaScript
const SomeExtension = {
tags: ['something'],
parse: function(parser, nodes, lexer) {
const [tag] = this.tags
const tok = parser.nextToken()
const args = parser.parseSignature(null, true)
parser.advanceAfterBlockEnd(tok.value)
const body = parser.parseUntilBlocks(tag, end${tag})
parser.advanceAfterBlockEnd()
return new nodes.CallExtension(this, 'run', args, [body])
},
run (args) {
return 'My modified extension content'
}
}
`
then you can use it in the template:
`njk
{{ 'some text' | someFilter }}

{% something %}
Some content
{% endsomething %}
`
and the result should be:
`html
My modified filter content
My modified extension content
`

$3

If you need asynchronous filter you can pass nunjucksFilter instead of nunjucksFilterCallback:
`JavaScript
import nunjucks from 'vite-plugin-nunjucks'

export default {
plugins: [
nunjucks({
nunjucksEnvironment: {
filters: {someFilter: {
async: true,
filter: someFilter
}},
}
}),
]
}
`

$3

You can use your own environment that you configure entirely
`JavaScript
import nunjucks from 'vite-plugin-nunjucks'

const env = new nunjucks.Environment(/ someOptions /)
env.addFilter('someFilter', someFilter);
env.addExtension('someExtension', SomeExtension);
export default {
plugins: [
nunjucks({nunjucksEnvironment: env}),
]
}
`

Options

| Parameter | Type | Default | Description |
| ----------- | ----------- | ----------- | ----------- |
| templatesDir | string | ./src/html | Absolute path where are HTML templates located. Example: path.resolve(process.cwd(), 'src', 'myTemplates')
| variables | Record | {} | Variables for each entry point. Example { 'index.html': {username:'John'} }
| nunjucksConfigure | nunjucks.ConfigureOptions | {noCache:true} | Configure options for Nunjucks
| nunjucksEnvironment | nunjucksEnvironmentOptions OR nunjucks.Environment | {noCache:true}` | Configure Nunjucks environment or pass your own env