# Nunjucks loader for webpack - `require` precompiled templates in webpack - supports `extends` and `include` - resolves template dependencies using `require` - bundles the nunjucks-slim browser runtime - use the version of nunjucks you want to as a peer dependency - supports experimental Jinja compatibility ## Usage [Documentation: Using loaders](http://webpack.github.io/docs/using-loaders.html) ### Recommended configuration Install: `npm install nunjucks-loader --save` Add to webpack.config to process all .njk and .nunjucks files: ``` javascript // file: webpack.config.js module.exports = { entry: './src/entry.js', output: { path: __dirname, filename: 'bundle.js' }, module: { loaders: [ { test: /\.(njk|nunjucks)$/, loader: 'nunjucks-loader' } ] } }; ``` Then use it in your module code without the `nunjucks!` prefix: ``` javascript // file: src/entry.js var tpl = require('./views/page.njk'); var html = tpl.render({ message: 'Foo that!' }); ``` #### Inline configuration (not recommended) If using the inline configuration (below), references inside of templates to other files (parents, imports etc) may not resolve correctly - hence it's preferable to use the webpack.config method above. ``` javascript var tpl = require("nunjucks!./views/page.njk"); var html = tpl.render({ message: 'Foo that!' }); ``` ### webpack.target = 'node' **The 2.x versions of this loader do not support node/UMD bundles.** If you need to support node or UMD with the bundle, the 1.x version (`npm install nunjucks-loader@1.0.7`) supports these targets. ### Filters and extensions A *require* filter is added by this package that allows you to use webpack to resolve file references. Eg. ``` {# use the raw-loader to replace 'readme.txt' with the contents of that file #} {{ 'raw!readme.txt' | require }} ``` A custom nunjucks.Environment is used by the loader, to configure the nunjucks environment: - To pass [nunjucks.Environment options](https://mozilla.github.io/nunjucks/api.html#environment), add a `opts` key to the nunjucks loader query in webpack.config.js - Create a file that will configure the environment. This should export a function that receives the nunjucks environment as its first argument. - Add a `config` key to the nunjucks-loader query in webpack.config.js - Add an optional `quiet` key to the loader query in webpack.config.js to suppress precompile warnings (see below) ``` javascript // file: src/nunjucks.config.js module.exports = function(env){ env.addFilter('asyncFoo', function(input, done){ setTimeout(function(){ done('[asyncFoo] ' + input); }, 1000) }, true); // env.addExtension(...) etc } // file: webpack.config.js module.exports = { entry: './src/entry.js', output: { path: __dirname, filename: 'bundle.js' }, module: { loaders: [ { test: /\.(njk|nunjucks)$/, loader: 'nunjucks-loader', query: { config: __dirname + '/src/nunjucks.config.js' } } ] } }; ``` __If using async filters or custom extensions with nunjucks__, they must be available before the template is precompiled. If the nunjucks config file depends on webpack resolve (such as loaders or custom module paths), the custom filters/extensions will not be available at precompile time. When/if this happens, you will receive the following warning in the console: *Cannot configure nunjucks environment before precompile* When using webpack resolve with the environment config and __not__ using async filters or custom extensions, the warning can be safely ignored - standard filters are still added to the environment at runtime. To remove the warning, pass the `quiet` option in the loader query. eg: ``` // file: webpack.config.js module.exports = { module: { loaders: [ { test: /\.(njk|nunjucks)$/, loader: 'nunjucks-loader', query: { config: __dirname + '/src/nunjucks.config.js', quiet: true // Don't show the 'Cannot configure nunjucks environment before precompile' warning } } ] } }; ``` ## Path resolution This loader modifies the way nunjucks resolves dependencies (eg `extends`, `import` and `include`) to work correctly with webpack. As a result, you may use `require` style relative paths in your templates. Add a `resolve.root` key to `webpack.config.js` to resolve your templates without using relative paths. ``` javascript // file: webpack.config.js module.exports = { resolve: { root: [ __dirname, __dirname + '/src/views' // Resolve templates to ./src/views ] } } ``` Alternatively, a `root` query parameter can be passed to the loader to set the root template directory. ``` javascript // webpack.config.js module.exports = { module: { loaders: [ { test: /\.(nunj|nunjucks)$/, loader: 'nunjucks-loader', query: { root: __dirname + '/path/to/templates' } } ] } } ``` ## Jinja/Python compatibility If [experimental support for Jinja compatibility](https://mozilla.github.io/nunjucks/api.html#installjinjacompat) is desired, pass the jinjaCompat option in the loader query. eg: ``` // file: webpack.config.js module.exports = { module: { loaders: [ { test: /\.(nunj|nunjucks)$/, loader: 'nunjucks-loader', query: { jinjaCompat: true } } ] } }; ``` This option will not provide full Jinja/Python compatibility, but will treat `True`/`False` like `true`/`false`, and augment arrays and objects with Python-style methods (such as `count`, `find`, `insert`, `get`, and `update`). Review the [jinja-compat source](https://github.com/mozilla/nunjucks/blob/master/src/jinja-compat.js) to see everything it adds. ## Tests `npm run test` Navigate to http://localhost:8080/test