Does Handlebars Have a Equivalent to Sass API Importers for Resolving Partials Imports Dynamically?

[JuanRojasC]

Description:

I am building an application that renders both Sass and Handlebars files. In the Sass API, there's an importers property that allows you to define where the API should look for files to import dynamically. I'm wondering if something similarly simple exists in Handlebars for resolving partials dynamically.

After some investigation, I found the invokePartial function in the Handlebars repository.

handlebars.js/lib/handlebars/runtime.js

Line 174 in 084e8fe

export function invokePartial(partial, name, context, helpers, partials, data, depths) {

I’ve partially achieved my goal by overriding it. Here’s my implementation:

Handlebars.VM.invokePartial = function (partial, variables, context, helpers, partials, data, depths) {
  var options = { partial: true, helpers: helpers, partials: partials, data: data, depths: depths };
  if (partial === undefined) {
    const componentRoute = `${variables.component}${(variables.component_variation ? `/${variables.component_variation}` : '')}`;
    const partialRoute = path.join(__customComponents, componentRoute, context.name + '.hbs');
    try {
      const partialContent = fs.readFileSync(partialRoute, 'utf-8');
      return Handlebars.compile(partialContent)(context, options);
    } catch (err) {
      throw new Error("The partial " + partialRoute + " could not be found");
    }
  } else if (partial instanceof Function) {
    return partial(context, options);
  }
};

This approach dynamically resolves partials based on custom paths constructed from variables. It works well when resolving the partials themselves, but fails when the partials make use of known helpers like #each or #with. For instance, if a partial uses {{#each items}}, I encounter an exception like this:

TypeError: Cannot read properties of undefined (reading 'each')
    at lookupProperty (/node_modules/handlebars/dist/cjs/handlebars/runtime.js:119:26)
    at Object.eval [as main] (eval at createFunctionContext (/node_modules/handlebars/dist/cjs/handlebars/compiler/javascript-compiler.js:262:23).

I suspect this issue arises because the helpers (knownHelpers) are not correctly passed or recognized in this custom implementation. Despite including the helpers object in the options, Handlebars still fails to resolve them.

The goal is to enable the use of pseudo-relative paths based on the entry .hbs file. For example, consider packageA, which contains main.hbs and example.hbs. The entry point is main.hbs, and inside it, the partial example.hbs is referenced. The desired outcome is for main.hbs to declare {{> example }} and, using invokePartial along with an injected variable, resolve example to packageA/example.hbs.

While a straightforward approach is to use Handlebars.registerPartial('example', ...), this is not scalable because the number of partials to register is unknown. Additionally, there could also be a packageB containing its own example.hbs, which needs to be resolved correctly based on the respective package context.

Question:

1. Is there a native feature or mechanism in Handlebars to dynamically resolve partials, similar to Sass's importers property?
2. If not, what adjustments should I make to the above implementation to ensure that known helpers like #each and #with are properly recognized and functional in dynamically resolved partials?
3. Are there alternative best practices for handling such dynamic resolution of partials in Handlebars?

[jaylinski]

I guess you can't use dynamic partials because packageB is not controlled by you and you can't change the "import"-statements?

[JuanRojasC]

I was able to solve this issue by overriding the resolvePartial (with warning Deprecated symbol used, consult docs for better alternative) function instead of invokePartial. The solution is tailored to dynamically resolve partials based on the context, which works perfectly for importing partials according to specific requirements.

The updated implementation, use the original logic of resolvePartial while introducing a mechanism to dynamically locate the partial file if it isn't initially found.

Handlebars.VM.resolvePartial = function(partial, context, options) {
  if (!partial) {
    if (options.name === '@partial-block') {
      partial = options.data['partial-block'];
    } else {
      partial = options.partials[options.name];
    }
  } else if (!partial.call && !options.name) {
    options.name = partial;
    partial = options.partials[partial];
  }

  // Custom logic for resolving partials based on context
  if (context.component && (context.component_variation || true)) {
    componentRouteCurrent = `/${context.component}${(context.component_variation ? `/${context.component_variation}` : '')}`;
  }

  if (!partial) {
    // Dynamically determine the partial file's path
    const partialRoute = path.join( __customComponents, componentRouteCurrent, options.name + '.hbs' );

    try {
      // Compile the resolved partial
      return Handlebars.compile(fs.readFileSync(partialRoute, 'utf-8'));
    } catch (er) {
      throw new Error(`The partial "${partialRoute}" could not be found`);
    }
  }

  return partial;
};

Key Details:

1. Preserving Original Behavior: The original logic of resolvePartial is retained for standard cases.
2. Custom Resolution Logic: If the partial isn't found in the standard locations, the custom logic dynamically resolves the file path based on the context variables (component, component_variation, etc.).
3. Dynamic Path Handling: The custom partialRoute is constructed using the context and the expected partial name, enabling scalable and reusable partial resolution.
4. Error Handling: A clear error is thrown if the partial file cannot be located, making debugging easier.

This approach essentially acts as a middleware: it first attempts to resolve the partial using the default logic, and if it fails, it falls back to the custom resolution logic. If this functionality could be implemented as an official feature in Handlebars, it would greatly enhance the framework's ability to handle dynamic partial loading. A middleware-like mechanism, where a user-defined function could intercept and extend the partial resolution logic, would be an excellent addition. This function could receive the context and other parameters, attempt to resolve the partial dynamically, and fall back to the default logic if needed.