{"id":13493745,"url":"https://github.com/ogonkov/nunjucks-loader","last_synced_at":"2025-10-23T15:30:54.976Z","repository":{"id":35021545,"uuid":"195884522","full_name":"ogonkov/nunjucks-loader","owner":"ogonkov","description":"Webpack loader for Nunjucks templates","archived":false,"fork":false,"pushed_at":"2023-03-23T04:57:20.000Z","size":295,"stargazers_count":28,"open_issues_count":9,"forks_count":7,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-30T19:11:18.250Z","etag":null,"topics":["html-webpack-plugin","loader","nunjucks","template-engine","templates","webpack","webpack-loader"],"latest_commit_sha":null,"homepage":"https://ogonkov.github.io/nunjucks-loader/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ogonkov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-07-08T20:51:42.000Z","updated_at":"2024-01-12T18:09:42.000Z","dependencies_parsed_at":"2024-06-18T18:11:41.832Z","dependency_job_id":null,"html_url":"https://github.com/ogonkov/nunjucks-loader","commit_stats":{"total_commits":97,"total_committers":3,"mean_commits":"32.333333333333336","dds":0.08247422680412375,"last_synced_commit":"74d84a5c2298de8d33b4621edc46c4d5ba45f173"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ogonkov%2Fnunjucks-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ogonkov%2Fnunjucks-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ogonkov%2Fnunjucks-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ogonkov%2Fnunjucks-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ogonkov","download_url":"https://codeload.github.com/ogonkov/nunjucks-loader/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237843930,"owners_count":19375230,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["html-webpack-plugin","loader","nunjucks","template-engine","templates","webpack","webpack-loader"],"created_at":"2024-07-31T19:01:18.412Z","updated_at":"2025-10-23T15:30:49.591Z","avatar_url":"https://github.com/ogonkov.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"[![npm package][npm-image]][npm-url] \n[![Coverage Status][coverage-image]][coverage-url] \n[![node][node]][node-url] \n[![Build Status][build-image]][build-url] \n![Dependencies Status][dependencies-image]\n\n# Nunjucks templates loader for Webpack\n\nThis Webpack loader compiles [Nunjucks][nunjucks-github] templates.\n[`html-webpack-plugin`][html-webpack-plugin-github] compatible. \n\n\u003e For Webpack 4 support use loader 2.x version\n\n## Install\n```bash\nnpm install --save-dev simple-nunjucks-loader\n```\n\nIf you don't use [dynamic assets](#dynamic-assets) in your code, then you could\nsave a bit on optional `glob` dependency:\n\n```bash\nnpm install --no-optional --save-dev simple-nunjucks-loader\n```\n\n## Usage\n\nThis loader will [precompile][nunjucks-docs-precompiling]\nNunjucks templates. It also includes Nunjunks (slim) runtime for browser.\n\nAdd loader to your `webpack` config as follows:\n\n**webpack.config.js**\n```js\nmodule.exports = {\n    module: {\n        rules: [\n            {\n                test: /\\.njk$/,\n                use: [\n                    {\n                        loader: 'simple-nunjucks-loader',\n                        options: {}\n                    }\n                ]\n            }\n        ]\n    }\n};\n```\n\n**template.njk**\n```nunjucks\n\u003cp\u003eHello, {{ username }}!\u003c/p\u003e\n```\n\n**index.js**\n```js\nimport template from './template.njk'\n\ndocument.body.innerHTML = template({\n  username: 'Mike'\n})\n```\n\nBundling of `index.js` above will render paragraph with text \"Hello, Mike!\" to\nthe page.\n\n[More examples](https://ogonkov.github.io/nunjucks-loader/#examples) on loader\nsite.\n\n## How it works\nBy default Nunjunks bundle all precompiled templates to\n`window.nunjucksPrecompiled`, then loads them via custom loader from this\nglobal object. If precompiled template reference some other template file,\nit is loaded from disk (in NodeJS environment), or fetched via `XMLHttpRequest`\nfrom internet and precompile downloaded template in runtime.\n\nBoth are not webpack-way for projects bundling.\n\nThis loader got template source, parse it with Nunjucks parser, to get AST of\ntemplate. This AST is iterated to get info on imported templates, used filters\nand extensions.\n\nNext step is precompile template, to make it faster. Loader injects own wrapper\nto avoid default behaviour with creating global `window.nunjucksPrecompiled`.\n\nOne final step is gather all parts together. Loader is inserts imports of\ntemplates, filters and extensions that somehow noted in template, this will make\nWebpack to rebuild template only when one of essential part is changed.\n\nThen loader expose module that will create separate environment with only\nrequired filters and extensions. This module is what you invoke to get your\ntemplate rendered.\n\n### Assets support\n\nLoader add own `{% static %}` tag, for loading assets, and track their change.\n\nSignature is same to `static` tag from Django.\n\n**template.njk**\n\n```nunjucks\n\u003cimg alt=\"\" src=\"{% static 'image.jpg' %}\" /\u003e\n```\n\nSee [more examples](https://ogonkov.github.io/nunjucks-loader/examples/assets/)\nof setup and using assets in loader.\n\n### Asynchronous support\n\nWhen loader found async tags or async filters or extensions in the template,\nit calls `render` with callback under the hood, and returns `Promise`,\ninstead of render result.\n\nBecause of asynchronous nature of Webpack assets loading, all assets, that\nloaded via `{% static %}` tag, make template to return `Promise` too.\n\n## Options\nLoader supports limited number of [Nunjuncks options][nunjucks-docs-configure].\nIt's doesn't support `watch` (we use `webpack` own dependencies watch),\n`noCache`, `web` settings and `express`.\n\nAll other options get passed to Nunjunks `Environment` during files loading.\n\n|Name|Type|Default|Description|\n|:--:|:--:|:-----:|:----------|\n|**[`jinjaCompat`](#jinjacompat)**|`{Boolean}`|`false`|Install Jinja syntax support in bundle|\n|**[`searchPaths`](#searchpaths)**|`{String}` or `{Array.\u003cstring\u003e}`|`.`|One or more paths to resolve templates paths|\n|**[`assetsPaths`](#assetspaths)**|`{String}` or `{Array.\u003cstring\u003e}`|`.`|Paths to resolve static assets. Works like [`STATICFILES_DIRS`][django-settings-staticfiles-dirs].|\n|**[`globals`](#globals)**|`Object.\u003cstring, string\u003e`|`{}`|Map global function to corresponding module|\n|**[`extensions`](#extensions)**|`Object.\u003cstring, string\u003e`|`{}`|Map extension to corresponding module|\n|**[`filters`](#filters)**|`Object.\u003cstring, string\u003e`|`{}`|Map filters to corresponding module|\n|\u003c!-- Add custom options above --\u003e**`autoescape`**|`{Boolean}`|`true`|See [Nunjuncks options][nunjucks-docs-configure] for description of options below|\n|**`throwOnUndefined`**|`{Boolean}`|`false`||\n|**`trimBlocks`**|`{Boolean}`|`false`||\n|**`lstripBlocks`**|`{Boolean}`|`false`||\n|**`tags`**|`{Object.\u003cstring, string\u003e}`|Default Jinja tags config|Override tags syntax|\n|**`dev`**|`{Boolean}`|`true` for development and `false` for production mode|Undocumented Nunjucks option, that will make stacktraces more useful|\n\n`tags` default to:\n```\n{\n    blockStart: '{%',\n    blockEnd: '%}',\n    variableStart: '{{',\n    variableEnd: '}}',\n    commentStart: '{#',\n    commentEnd: '#}'\n}\n```\n\n### jinjaCompat\n\nInstalls Jinja syntax. This option install it for whole bundle.\n\n### searchPaths\n\nLoader is searching for full template relative to given string(s) from\n`searchPath` option (or project root, if no paths given).\n\nPath to file couldn't be outside of folders above.\n\n**webpack.config.js**\n```js\nmodule.exports = {\n    module: {\n        rules: [\n            {\n                test: /\\.njk$/,\n                use: [{\n                    loader: 'simple-nunjucks-loader',\n                    options: {\n                        searchPaths: [\n                            'django_app_a/templates',\n                            'django_app_b/templates'\n                        ]\n                    }\n                }]\n            }\n        ]\n    }\n};\n```\n\n### assetsPaths\n\nList of paths where loader should search for assets.\n\n```js\nmodule.exports = {\n    module: {\n        rules: [\n            {\n                test: /\\.njk$/,\n                use: [{\n                    loader: 'simple-nunjucks-loader',\n                    options: {\n                        assetsPaths: [\n                            'django_app_a/static',\n                            'django_app_b/static'\n                        ]\n                    }\n                }]\n            }\n        ]\n    }\n};\n```\n\n### globals\n\nSet global function and import path, that should return function to use.\nIt the same function that [`env.addGlobal`][nunjucks-docs-addglobal] using.\n\n**webpack.config.js**\n```js\nmodule.exports = {\n    module: {\n        rules: [\n            {\n                test: /\\.njk$/,\n                use: [{\n                    loader: 'simple-nunjucks-loader',\n                    options: {\n                        globals: {\n                            _: 'lodash',\n                            globalFn: path.join(__dirname, 'global-fn.js')\n                        }\n                    }\n                }]\n            }\n        ]\n    }\n};\n```\n\n**global-fn.js**\n```js\nmodule.exports = function globalFn(foo, bar) {\n    return `Do anything with ${foo} and ${bar}`;\n};\n```\n\n### extensions\n\nSet map of extensions that would be imported before each template render.\nExtension should return instance, that would be added via\n[`env.addExtension`][nunjucks-docs-addextension].\n\n**webpack.config.js**\n```js\nmodule.exports = {\n    module: {\n        rules: [\n            {\n                test: /\\.njk$/,\n                use: [{\n                    loader: 'simple-nunjucks-loader',\n                    options: {\n                        extensions: {\n                            CustomExtension: path.join(__dirname, 'extension.js')\n                        }\n                    }\n                }]\n            }\n        ]\n    }\n};\n```\n\n\u003e :boom: Using ES modules syntax for extensions\n\u003e [is not yet possible](https://github.com/ogonkov/nunjucks-loader/issues/81)\n\n**extension.js**\n```js\n// You should use slim bundle to make it work in browser\nconst nunjucks = require('nunjucks/browser/nunjucks-slim');\n\n// See example in docs\n// https://mozilla.github.io/nunjucks/api.html#custom-tags\nclass CustomExtension {}\n\nmodule.exports = new CustomExtension();\n```\n\nLoader trying to guess which extensions are really used, and keep only required\nimports.\n\n### filters\n\nMap of filters, that would be imported before each template render.\nFilter should return instance, that would be added via\n[`env.addFilter`][nunjucks-docs-addfilter].\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n    module: {\n        rules: [\n            {\n                test: /\\.njk$/,\n                use: [{\n                    loader: 'simple-nunjucks-loader',\n                    options: {\n                        filters: {\n                            filter: path.join(__dirname, 'filter.js')\n                        }\n                    }\n                }]\n            }\n        ]\n    }\n};\n```\n\n\u003e :boom: Using ES modules syntax for filters\n\u003e [is not yet possible](https://github.com/ogonkov/nunjucks-loader/issues/81)\n\n**filter.js**\n\n```js\nmodule.exports = function filter(val, param) {\n    return `${val + param}`;\n};\n```\n\n**template.njk**\n\n```nunjucks\n{{ foo_var | filter(3) }}\n```\n\nNunjucks is not aware that filter is asynchronous when parse template to AST. \nBecause of that, you should mark filter as async. To do that, filter module\nshould export `async` flag:\n\n**async-filter.js**\n\n```js\nfunction asyncFilter(val, param, callback) {\n    setTimeout(function() {\n        callback(null, val + param);\n    }, 1000);\n}\n\nasyncFilter.async = true;\n\nmodule.exports = asyncFilter;\n```\n\n[nunjucks-github]:https://github.com/mozilla/nunjucks\n[html-webpack-plugin-github]:https://github.com/jantimon/html-webpack-plugin\n[html-webpack-plugin-options]:https://github.com/jantimon/html-webpack-plugin/#options\n[expose-loader-github]:https://github.com/webpack-contrib/expose-loader\n[nunjucks-docs-precompiling]:https://mozilla.github.io/nunjucks/api.html#precompiling\n[nunjucks-docs-configure]:https://mozilla.github.io/nunjucks/api.html#configure\n[nunjucks-docs-addglobal]:https://mozilla.github.io/nunjucks/api.html#addglobal\n[nunjucks-docs-addextension]:https://mozilla.github.io/nunjucks/api.html#addextension\n[nunjucks-docs-addfilter]:https://mozilla.github.io/nunjucks/api.html#addfilter\n[django-settings-staticfiles-dirs]: https://docs.djangoproject.com/en/1.11/ref/settings/#std:setting-STATICFILES_DIRS\n\n[npm-image]:https://img.shields.io/npm/v/simple-nunjucks-loader.svg\n[npm-url]:http://npmjs.org/package/simple-nunjucks-loader\n[coverage-image]:https://coveralls.io/repos/github/ogonkov/nunjucks-loader/badge.svg?branch=master\n[coverage-url]:https://coveralls.io/github/ogonkov/nunjucks-loader?branch=master\n[node]: https://img.shields.io/node/v/simple-nunjucks-loader.svg\n[node-url]: https://nodejs.org\n[build-image]:https://github.com/ogonkov/nunjucks-loader/workflows/Tests/badge.svg?branch=master\n[build-url]:https://github.com/ogonkov/nunjucks-loader/actions?query=branch%3Amaster+workflow%3ATests\n[dependencies-image]:https://api.dependabot.com/badges/status?host=github\u0026repo=ogonkov/nunjucks-loader\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fogonkov%2Fnunjucks-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fogonkov%2Fnunjucks-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fogonkov%2Fnunjucks-loader/lists"}