Supports:
📂 - Templates and layouts 🔗
📃 - Variables for each entry point (HTML) and global scope
🎠- Custom filters 🔗 and extensions 🔗
Yarn
yarn add vite-plugin-nunjucks -D
or npm
npm i vite-plugin-nunjucks --save-dev
Use plugin in your Vite config (vite.config.ts
)
import nunjucks from 'vite-plugin-nunjucks'
export default {
plugins: [
nunjucks(),
]
}
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>
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 content
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
}},
}
}),
]
}
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}),
]
}
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 |