KnownHelpersOnly flag limits helper usage to built‑in helpers only

Answer to Specific Questions

1. Can you declare custom helpers with --knownHelpersOnly?
   Yes. When compiling, pass a knownHelpers map that contains each helper you want to allow. The map’s keys are the helper names, and the values are the functions. Example:

   const Handlebars = require('handlebars');
   const template = Handlebars.compile(source, {
     knownHelpersOnly: true,
     knownHelpers: {
       myHelper: function (context, options) { return context + options.hash.foo; }
     }
   });
   

   This makes {{myHelper}} available while rejecting any other helper names.
2. Must all partials be passed explicitly when using --knownHelpersOnly?
   Yes. The precompiler does not perform automatic discovery of partials. You must either inline them in the template or supply them via the partials option or the --partials CLI flag. The runtime lookup for {{> myPartial}} is disabled unless the partial is explicitly provided.
3. What happens if a template contains a dynamic helper or partial name with the flag enabled?
   During rendering, Handlebars throws a TypeError (or a custom error in newer releases) if it encounters a helper or partial that is not in the known list. Dynamic names such as {{{var}}} or {{> (lookup . "p")}} are treated as attempts to resolve a helper/partial at runtime and will fail immediately.

Confirmed Facts

• The knownHelpersOnly option is available from Handlebars 4.7 onward.
• When the flag is true, the compiler ignores any helper not present in knownHelpers and the runtime throws an error instead of silently ignoring it.
• Partials must be supplied explicitly; the CLI cannot auto‑discover them when the flag is set.
• Dynamic helper or partial names are prohibited; they trigger a runtime error.

Practical Steps for Your Pipeline

1. Collect all custom helpers you need and create a single module that exports them as an object.

   module.exports = {
     capitalize: (str) => str.charAt(0).toUpperCase() + str.slice(1),
     formatDate: (date) => new Date(date).toLocaleDateString()
   };
   

2. When invoking the Handlebars precompiler (CLI or programmatic), pass the helpers map:

   handlebars --knownHelpersOnly true --knownHelpers ./helpers.js --partials ./partials/ --output compiled.js
   

3. Ensure every partial referenced in a template is either inlined or listed in the --partials option.
4. Run a quick sanity test: try rendering a template that uses a helper not in the map and confirm it throws an error. Then add the helper and verify rendering succeeds.

One Missing Diagnostic Detail

To fine‑tune the recommendation, could you confirm the exact Handlebars version you’re targeting (e.g., 4.7.7, 4.9.0)? Some minor differences in error messages or option names exist across releases.