vite-plugin-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
Configuration
Use plugin in your Vite config (vite.config.ts)
import nunjucks from 'vite-plugin-nunjucks'
export default {
plugins: [
nunjucks(),
]
}Example
Input (src/index.html):
{% extends "src/html/layout.html" %}
{% include "src/html/hello.html" %}
{% block content %}
{% if username %}
Username: {{ username }}
{% else %}
Variable <code>username</code> is missing
{% endif %}
{% endblock %}Template (src/html/layout.html):
<!DOCTYPE html>
<html lang="en">
<head></head>
<body>
{% block content %}
{% endblock %}
</body>
</html>Template (src/html/hello.html):
<h1>Hello world!</h1>Vite config (vite.config.ts)
import nunjucks from 'vite-plugin-nunjucks'
export default {
plugins: [
nunjucks({ variables: { 'index.html': { username: 'John' }}} ),
]
}Output (dist/index.html)
<!DOCTYPE html>
<html lang="en">
<head></head>
<body>
<h1>Hello world!</h1>
Username: John
</body>
</html>Environment
Since v0.1.4 you can pass custom filters and extensions to the environment.
Config example:
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)
const someFilter = (val) => {
// ... some logic
return 'My modified filter content';
}and extension like this:
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:
{{ 'some text' | someFilter }}
{% something %}
Some content
{% endsomething %}and the result should be:
My modified filter content
My modified extension contentAsync filter
If you need asynchronous filter you can pass nunjucksFilter instead of nunjucksFilterCallback:
import nunjucks from 'vite-plugin-nunjucks'
export default {
plugins: [
nunjucks({
nunjucksEnvironment: {
filters: {someFilter: {
async: true,
filter: someFilter
}},
}
}),
]
}Own environment
You can use your own environment that you configure entirely
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<string, object> |
{} |
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 |