@dryfeld/nunjucks-loader 4.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Ben Daley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/index.js

@@ -0,0 +1,154 @@
+/*******************************************************************
+ *
+ *  This module was heavily inspired by nunjucksify.
+ *  (https://www.npmjs.com/package/nunjucksify)
+ *
+ *  Full credit to the original authors.
+ *
+ ******************************************************************/
+
+const nunjucks = require('nunjucks');
+const path = require('path');
+let hasRun = false;
+let env;
+let pathToConfigure;
+let jinjaCompatStr;
+let root;
+
+module.exports = function (source) {
+    if (this.target !== 'web') {
+        throw new Error('[nunjucks-loader] non-web targets are not supported');
+    }
+
+    this.cacheable();
+
+    let envOpts;
+
+    if (!hasRun) {
+        const query = new URLSearchParams(this.query);
+        envOpts = query.opts || {};
+        if (query){
+
+            env = new nunjucks.Environment([], envOpts);
+
+            if (query.config){
+                pathToConfigure = query.config;
+                try {
+                    const configure = require(query.config);
+                    configure(env);
+                }
+                catch (e) {
+                    if (e.code === 'MODULE_NOT_FOUND') {
+                        if (!query.quiet) {
+                            const message = 'Cannot configure nunjucks environment before precompile\n' +
+                                    '\t' + e.message + '\n' +
+                                    'Async filters and custom extensions are unsupported when the nunjucks\n' +
+                                    'environment configuration depends on webpack loaders or custom module\n' +
+                                    'resolve rules. If you are not using async filters or custom extensions\n' +
+                                    'with nunjucks, you can safely ignore this warning.'
+                                ;
+                            this.emitWarning(message);
+                        }
+                    }
+                    else {
+                        this.emitError(e.message);
+                    }
+                }
+            }
+
+            // Specify the template search path, so we know from what directory
+            // it should be relative to.
+            if (query.root) {
+                root = query.root;
+            }
+
+            // Enable experimental Jinja compatibility to be enabled
+            if(query.jinjaCompat){
+                jinjaCompatStr = 'nunjucks.installJinjaCompat();\n';
+            }
+        }
+        else {
+            env = new nunjucks.Environment([]);
+        }
+        hasRun = true;
+    }
+
+    const name = path.relative(root || this.rootContext || this.options.context, this.resourcePath);
+
+    let nunjucksCompiledStr = nunjucks.precompileString(source, {
+            env: env,
+            name: name
+        });
+
+    nunjucksCompiledStr = nunjucksCompiledStr.replace(/window\.nunjucksPrecompiled/g, 'nunjucks.nunjucksPrecompiled');
+
+    // ==============================================================================
+    // replace 'require' filter with a webpack require expression (to resolve assets)
+    // ==============================================================================
+    const filterReg = /env\.getFilter\(\"require\"\)\.call\(context, \"(.*?)\"/g;
+    nunjucksCompiledStr = nunjucksCompiledStr.replace(filterReg, 'require("$1"');
+
+    // ================================================================
+    // Begin to write the compiled template output to return to webpack
+    // ================================================================
+    let compiledTemplate = '';
+    compiledTemplate += 'var nunjucks = require("nunjucks/browser/nunjucks-slim");\n';
+    if (jinjaCompatStr) {
+        compiledTemplate += jinjaCompatStr + '\n';
+    }
+    compiledTemplate += 'var env;\n';
+    compiledTemplate += 'if (!nunjucks.currentEnv){\n';
+    compiledTemplate += '\tenv = nunjucks.currentEnv = new nunjucks.Environment([], ' + JSON.stringify(envOpts) + ');\n';
+    compiledTemplate += '} else {\n';
+    compiledTemplate += '\tenv = nunjucks.currentEnv;\n';
+    compiledTemplate += '}\n';
+    if (pathToConfigure) {
+        compiledTemplate += 'var configure = require("' + path.relative(this.context, pathToConfigure) + '")(env);\n';
+    }
+
+
+
+
+    // =========================================================================
+    // Find template dependencies within nunjucks (extends, import, include etc)
+    // =========================================================================
+    //
+    // Create an object on nunjucks to hold the template dependencies so that they persist
+    // when this loader compiles multiple templates.
+    compiledTemplate += 'var dependencies = nunjucks.webpackDependencies || (nunjucks.webpackDependencies = {});\n';
+
+    const templateReg = /env\.getTemplate\(\"(.*?)\"/g;
+    let match;
+
+    // Create an object to store references to the dependencies that have been included - this ensures that a template
+    // dependency is only written once per file, even if it is used multiple times.
+    const required = {};
+
+    // Iterate over the template dependencies
+    while (match = templateReg.exec(nunjucksCompiledStr)) {
+        const templateRef = match[1];
+        if (!required[templateRef]) {
+            // Require the dependency by name, so it gets bundled by webpack
+            compiledTemplate += 'dependencies["' + templateRef + '"] = require( "' + templateRef + '" );\n';
+            required[templateRef] = true;
+        }
+    }
+
+
+
+    compiledTemplate += '\n\n\n\n';
+
+    // Include a shim module (by reference rather than inline) that modifies the nunjucks runtime to work with the loader.
+    compiledTemplate += 'var shim = require("' + path.resolve(this.context, __dirname + '/runtime-shim') + '");\n';
+    compiledTemplate += '\n\n';
+
+    // Write the compiled template string
+    compiledTemplate += nunjucksCompiledStr + '\n';
+
+    compiledTemplate += '\n\n';
+
+    // export the shimmed module
+    compiledTemplate += 'module.exports = shim(nunjucks, env, nunjucks.nunjucksPrecompiled["' + name + '"] , dependencies)';
+
+    return compiledTemplate;
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@dryfeld/nunjucks-loader",
+  "version": "4.0.0",
+  "description": "A nunjucks loader for webpack.",
+  "main": "index.js",
+  "scripts": {
+    "test": "webpack-dev-server --config test/webpack.config.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/at0g/nunjucks-loader.git"
+  },
+  "keywords": [
+    "webpack",
+    "nunjucks",
+    "nunj",
+    "loader",
+    "template"
+  ],
+  "author": "Ben Daley <ben@fanboy.io>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/at0g/nunjucks-loader/issues"
+  },
+  "homepage": "https://github.com/at0g/nunjucks-loader",
+  "peerDependencies": {
+    "nunjucks": ">= 2.5.0 <= 4.0.0"
+  },
+  "devDependencies": {
+    "chai": "^5.1.0",
+    "mocha-loader": "^5.1.5",
+    "nunjucks": "^3.2.4",
+    "raw-loader": "^4.0.2",
+    "slash": "^5.1.0",
+    "webpack": "^5.90.3",
+    "webpack-cli": "^5.1.4",
+    "webpack-dev-server": "^5.0.2"
+  }
+}

package/readme.md

@@ -0,0 +1,236 @@
+# 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

package/runtime-shim.js

@@ -0,0 +1,46 @@
+module.exports = function (nunjucks, env, obj, dependencies){
+
+    const oldRoot = obj.root;
+
+    obj.root = function( env, context, frame, runtime, ignoreMissing, cb ) {
+        const oldGetTemplate = env.getTemplate;
+        env.getTemplate = function (name, ec, parentName, ignoreMissing, cb) {
+            if( typeof ec === "function" ) {
+                cb = ec = false;
+            }
+            const _require = function (name) {
+                try {
+                    // add a reference to the already resolved dependency here
+                    return dependencies[name];
+                }
+                catch (e) {
+                    if (frame.get("_require")) {
+                        return frame.get("_require")(name);
+                    }
+                    else {
+                        console.warn('Could not load template "%s"', name);
+                    }
+                }
+            };
+
+            const tmpl = _require(name);
+            frame.set("_require", _require);
+
+            if( ec ) tmpl.compile();
+            cb( null, tmpl );
+        };
+
+        oldRoot(env, context, frame, runtime, ignoreMissing, function (err, res) {
+            env.getTemplate = oldGetTemplate;
+            cb( err, res );
+        });
+    };
+
+    const src = {
+        obj: obj,
+        type: 'code'
+    };
+
+    return new nunjucks.Template(src, env);
+
+};