Merge pull request #103 from mixmaxhq/pure-init

feat: support pure helper definitions

Author: skeggse

README.md

@@ -4,11 +4,11 @@
 
 Features:
 
-* Import Handlebars templates as ES6 modules
-* Support for Handlebars [helpers](#helpers) and partials
-* [Precompiles](http://handlebarsjs.com/precompilation.html) templates so your application only needs the Handlebars runtime
-* Handlebars runtime [included](#handlebars)
-* Optional rendering to [jQuery collections](#jquery) vs. raw strings
+- Import Handlebars templates as ES6 modules
+- Support for Handlebars [helpers](#helpers) and partials
+- [Precompiles](http://handlebarsjs.com/precompilation.html) templates so your application only needs the Handlebars runtime
+- Handlebars runtime [included](#handlebars)
+- Optional rendering to [jQuery collections](#jquery) vs. raw strings
 
 ## Installation
 
@@ -31,15 +31,14 @@ var rollup = require('rollup');
 var handlebars = require('rollup-plugin-handlebars-plus');
 var rootImport = require('rollup-plugin-root-import');
 
-
 var partialRoots = [`${__dirname}/src/client/js/views/`, `${__dirname}/src/common/views/`];
 
 rollup({
   entry: 'main.js',
   plugins: [
     // Required by use of `partialRoot` below.
     rootImport({
-      root: partialRoots
+      root: partialRoots,
     }),
     handlebars({
       handlebars: {
@@ -55,14 +54,20 @@ rollup({
         // Options to pass to Handlebars' `parse` and `precompile` methods.
         options: {
           // Whether to generate sourcemaps for the templates
-          sourceMap: true // Default: true
-        }
+          sourceMap: true, // Default: true
+        },
       },
 
       // The ID(s) of modules to import before every template, see the "Helpers" section below.
       // Can be a string too.
       helpers: ['/utils/HandlebarsHelpers.js'], // Default: none
 
+      // Whether to register the defined helpers at template declaration in a way that would allow
+      // the initialization call to be elided if the template is never used. Useful in a library
+      // context where the templates might all get tree-shaken away, leaving no need for the
+      // helpers. Does nothing if helpers is empty.
+      helpersPureInitialize: true, // Default: false
+
       // In case you want to compile files with other extensions.
       templateExtension: '.html', // Default: '.hbs'
 
@@ -74,10 +79,10 @@ rollup({
       partialRoot: partialRoots, // Default: none
 
       // The module ID of jQuery, see the "jQuery" section below.
-      jquery: 'jquery' // Default: none
-    })
-  ]
-})
+      jquery: 'jquery', // Default: none
+    }),
+  ],
+});
 ```
 
 lets you do this:
@@ -114,16 +119,16 @@ rollup({
   entry: 'main.js',
   plugins: [
     handlebars({
-      helpers: ['/utils/HandlebarsHelpers.js']
-    })
-  ]
-})
+      helpers: ['/utils/HandlebarsHelpers.js'],
+    }),
+  ],
+});
 ```
 
 ```js
 // /utils/HandlebarsHelpers.js
-export default function(Handlebars) {
-  Handlebars.registerHelper('encodeURIComponent', function(text) {
+export default function (Handlebars) {
+  Handlebars.registerHelper('encodeURIComponent', function (text) {
     return new Handlebars.SafeString(encodeURIComponent(text));
   });
 }
@@ -168,9 +173,9 @@ rollup({
     commonjs({
       include: 'node_modules/**',
     }),
-    handlebars()
-  ]
-})
+    handlebars(),
+  ],
+});
 ```
 
 In case you need the default runtime ID, it's available as `handlebars.runtimeId`. This might be
@@ -192,8 +197,8 @@ import Template from './index.html';
 var MyView = Backbone.View.extend({
   render() {
     this.setElement(Template());
-  }
-})
+  },
+});
 ```
 
 or by customizing the template using jQuery's APIs:
@@ -206,7 +211,7 @@ var tooltip = TooltipTemplate();
 
 tooltip.css({
   left: 50,
-  top: 100
+  top: 100,
 });
 
 $('body').append(tooltip);
@@ -223,10 +228,10 @@ rollup({
   entry: 'main.js',
   plugins: [
     handlebars({
-      jquery: 'jquery'
-    })
-  ]
-})
+      jquery: 'jquery',
+    }),
+  ],
+});
 ```
 
 Curious about how to ID jQuery when it's a global i.e. you're _not_ bundling it?

src/index.js

@@ -10,6 +10,13 @@ const DEFAULT_HANDLEBARS_ID = path.relative(
   require.resolve('handlebars/runtime')
 );
 
+const INTERNAL_INIT_ID = '\0handlebarsPlusHelpersInit';
+
+const escapePath = (path) => path.replace(/\\/g, '\\\\');
+
+const nonEmptyOr = (array, fallback) => (array.length ? array : fallback);
+const asArrayOr = (value, fallback) => nonEmptyOr([].concat(value || []), fallback);
+
 /**
  * Constructs a Rollup plugin to compile Handlebars templates.
  *
@@ -74,7 +81,36 @@ function handlebars(options) {
   const Handlebars = options.handlebars.module || require('handlebars');
   const ImportScanner = require('./ImportScanner')(Handlebars);
 
+  const hbsImport = `import Handlebars from '${escapePath(options.handlebars.id)}';\n`;
+
+  const wrapTemplateDefinition = options.helpersPureInitialize
+    ? (defineTemplate, initExpr) =>
+        defineTemplate((expr) => `(function() {${initExpr};return ${expr};})()`)
+    : (defineTemplate, initExpr) => `${initExpr};\n${defineTemplate()}`;
+
+  // Support `helpers` being singular or plural.
+  const helpers = asArrayOr(options.helpers, null);
+
   return {
+    resolveId: (id) => (helpers && id === INTERNAL_INIT_ID ? id : undefined),
+
+    load(id) {
+      if (!helpers || id !== INTERNAL_INIT_ID) return;
+
+      let body = hbsImport;
+      body += '';
+
+      const initExpr = helpers.map((helperPath, i) => {
+        const ref = `Helpers${i}`;
+        body += `import ${ref} from '${escapePath(helperPath)}';\n`;
+        return `  ${ref}.__initialized || (${ref}(Handlebars), ${ref}.__initialized = true);\n`;
+      });
+
+      body += `export default function() {\n${initExpr.join('')}}\n`;
+
+      return { code: body, map: { mappings: '' } };
+    },
+
     transform(code, id) {
       if (!id.endsWith(options.templateExtension)) return;
 
@@ -95,28 +131,21 @@ function handlebars(options) {
         template = template.code;
       }
 
-      const escapePath = (path) => path.replace(/\\/g, '\\\\');
-
-      let body = `import Handlebars from '${escapePath(options.handlebars.id)}';\n`;
+      let body = hbsImport;
       if (options.jquery) body += `import $ from '${escapePath(options.jquery)}';\n`;
 
-      if (options.helpers) {
-        // Support `helpers` being singular or plural.
-        [].concat(options.helpers).forEach((helpers, i) => {
-          body += `import Helpers${i} from '${escapePath(helpers)}';\n`;
-          body += `if (!Helpers${i}.__initialized) {\n`;
-          body += `  Helpers${i}(Handlebars);\n`;
-          body += `  Helpers${i}.__initialized = true;\n`;
-          body += `}\n`;
-        });
-      }
+      body += `import init from '${INTERNAL_INIT_ID}';\n`;
 
       for (const partial of scanner.partials) {
         // Register the partial dependencies as partials.
         body += `import '${escapePath(partial)}${options.templateExtension}';\n`;
       }
 
-      body += `var Template = /*#__PURE__*/Handlebars.template(${template});\n`;
+      body += wrapTemplateDefinition(
+        (wrapExpression = (expr) => expr) =>
+          `var Template = /*#__PURE__*/${wrapExpression(`Handlebars.template(${template})`)};\n`,
+        'init()'
+      );
 
       if (options.isPartial(name)) {
         let partialName = id;