ESHOPMANESHOPMAN Logo
Our Blog

Navigating HubSpot React Themes: The Truth About `include` Tags and 'Missing Template' Bugs

Navigating HubSpot React Themes: The Truth About `include` Tags and 'Missing Template' Bugs

Ever hit a "Missing Template" error in your HubSpot React project when using the familiar include tag? You're not alone! This exact issue recently sparked a lively discussion in the HubSpot Community, highlighting crucial nuances in HubSpot's evolving CMS. For ESHOPMAN, ensuring your HubSpot-powered built in ecommerce system runs smoothly means understanding these technical deep dives. Let's explore this community insight.

The `include` Tag Conundrum in React Projects

The original poster in the HubSpot Community faced a challenge: migrating a large HubL theme to HubSpot's "React Project" framework. They encountered a persistent "Missing Template" error when attempting to use the include tag to pull a partial template into a module. Despite the partial existing and the path seeming correct, the module on a live page displayed:

This was puzzling, especially since the template was clearly visible in the project UI:

Screenshot showing a partial template existing in the HubSpot project UI

The module's structure included `module.hubl.html` attempting to include `partial-test.hubl.html` like this:

This is a test module.

{% include '@projects/my-cms-theme/theme/my-theme/templates/partials/partial-test.hubl.html' %}

The core question: why wasn't this working as expected?

The Solution: Macros for Modules, `include` for Templates

A helpful community expert quickly clarified that the include tag is primarily designed for use within HubL templates, not modules or React themes. For modules, the recommended and more robust approach is to leverage import with HubL macros. This allows for structured code reuse within your module logic.

How to Use Macros for Reusable Partials in Modules

  1. Define your partial as a macro file (e.g., `_test.html`): Ensure it's marked as a utility file with `templateType: "none"` and `isAvailableForNewContent: false`.
    2. 

{% macro test_macro(some_content) %}
    
    {{some_content}}
    
{% endmacro %}
  2. Import and call the macro in your module (`module.html`): Use the `from` keyword, specifying the path relative to your theme's root, then invoke the macro with any necessary variables.
    3. {% from "path/to/_test.html" import test_macro %}

...

{{test_macro(module.some_text) }} {# module.some_text is a text field in the module #}

While the original poster noted that `include` tags had worked in modules on their older HubL site, this highlights a key difference in best practices for newer React Project environments. Macros are the "more correct" and officially supported way for modular code reuse.

React vs. HubL Themes: A Strategic Choice

The discussion broadened to the ongoing debate: when to choose React themes over traditional HubL themes? This is a vital strategic decision for any business leveraging HubSpot, especially for those managing a built in ecommerce system where development efficiency and site performance are paramount.

Arguments against React themes for typical marketing sites included:

  • Development is local-only, bypassing the Design Manager.
  • Every change requires compilation and pushing.
  • Can be perceived as "overkill" for largely static content.

Conversely, the original poster's reasons for migrating to React were compelling:

  • Aligning with existing React expertise and client preferences.
  • Proactive future-proofing against potential "Legacy" status for HubL themes.

A community expert, however, reassured that HubL themes are unlikely to disappear, citing HubSpot's history of long-term support for older systems. They suggested that while React themes offer benefits for complex applications, they might be excessive for static CMS assets and still carry a "beta" feel with various quirks.

ESHOPMAN Team Comment

This discussion perfectly illustrates the challenges and opportunities in HubSpot CMS development. While the original poster's `include` tag issue was a specific technical hurdle, the broader conversation about React vs. HubL themes is highly relevant for anyone building a robust online presence or a built in ecommerce system on HubSpot. We strongly advocate for understanding HubSpot's recommended best practices and leveraging tools like macros for modularity. While React offers modern development paradigms, it's essential to weigh its complexity against your project's actual needs and team's expertise. Don't chase the newest tech just because it's new; choose the right tool for the job to ensure long-term maintainability and performance for your storefront.

Key Takeaways for HubSpot Developers & Marketers

For HubSpot users, RevOps professionals, and marketers alike, understanding these CMS nuances is crucial for a smooth operation:

  1. Embrace Macros for Modules: For reusable components within modules, `import` and macros are the go-to. Save `include` for traditional HubL templates.
  2. Strategic Theme Selection: Carefully weigh the pros and cons of React vs. HubL themes based on your team's skills, project complexity, and long-term goals.
  3. Stay Informed: HubSpot's ecosystem evolves. Regular checks on community discussions and developer documentation will keep you ahead of the curve.

Navigating HubSpot's CMS can be intricate, but with these insights, you can build powerful, efficient, and maintainable experiences for your customers. Happy coding!

Share: