Skip to content

Jax-p/vite-plugin-nunjucks

Repository files navigation

vite-plugin-nunjucks

Node.js CI npm Downloads

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

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 content

Async 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')
useContextPathKey boolean false If true entry point keys use path . Example { '/index.html': {active:'Home'}, '/about/index.html': {active: 'About'} }
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