Upgrade Nested Modules in Hubspot Design Manager

Working in Hubspot design manager, you may still rely on older nested modules that make templates harder to maintain and slow for content editors. Hubspot now recommends replacing these legacy nested modules with modern module fields so you can manage content more efficiently and reduce layout issues in your templates.

This guide walks you through when and how to upgrade nested modules, what each option does, and how to troubleshoot common problems during the process.

What Are Nested Modules in Hubspot?

Nested modules are legacy reusable modules that were commonly used to bundle multiple modules together for repeated use across templates. They allowed you to create a group of modules and then drop that group into a layout. However, they have several limitations:

• They can cause unexpected layout behavior.
• They make content editing less intuitive.
• They complicate template organization and updates.

To improve performance and editing flexibility, Hubspot now encourages converting these nested modules into module fields that live directly on the parent module.

Where to Upgrade Nested Modules in Hubspot

All module upgrades happen inside the design manager. You will see upgrade options on eligible modules, typically under the Fields or Content tab depending on your layout.

Before you begin, make sure you:

• Have design tools access in your Hubspot account.
• Understand which templates and pages use the module you plan to upgrade.
• Make a backup or clone of critical templates in case you need to revert changes.

Hubspot Upgrade Options for Nested Modules

There are two main upgrade options for nested modules in Hubspot: converting nested module fields, and converting template layouts that include nested modules.

Convert Nested Module Fields in Hubspot

When you open a module that currently uses nested modules, you may see an in-editor prompt or banner to convert those nested module fields. This process replaces legacy nested module references with native module fields.

Steps to Convert Nested Module Fields

1. Open Design Manager in your Hubspot portal.
2. Locate and open the module that contains the nested module field.
3. Look for a notice or button offering to Upgrade or Convert nested modules.
4. Review the summary of what will change, including field mappings.
5. Click the upgrade button to convert the nested module to module fields.
6. Save and publish the module once the conversion finishes.

After the conversion, the content that previously lived inside the nested module will appear as normal fields in the parent module, making it easier for content editors to see and adjust individual items.

Convert Template Layouts with Hubspot Nested Modules

Some older templates still include nested modules directly in the layout. In those cases, you will need to upgrade the layout itself so it no longer depends on nested modules.

Steps to Upgrade Template Layouts

1. In design manager, navigate to the template that uses the nested module.
2. Open the layout editor and locate the nested module area.
3. Check for an Upgrade or Convert prompt on the module group.
4. Follow the guided upgrade process, which may include:

• Mapping nested module fields to new module fields.
• Confirming how repeated content should display.
• Replacing legacy module calls with updated structures.

5. Save the layout and publish templates or child templates that depend on it.

Once upgraded, the template will use modern module structures instead of nested modules, improving performance and clarity for editors.

Content Preservation During Hubspot Upgrades

When you upgrade nested modules in Hubspot, the system attempts to preserve content wherever possible. However, the exact behavior depends on how many times a nested module is used and how its fields map to the new structure.

• In many cases, content moves cleanly into new module fields.
• Sometimes, content may be stored in a generalized field until you manually reorganize it.
• If a nested module field cannot be mapped directly, you may see a warning that manual adjustments are required.

After upgrading, always test the affected templates on key pages to confirm that text, images, and dynamic content display as expected.

Troubleshooting Hubspot Nested Module Upgrades

Occasionally, upgrading nested modules in Hubspot can lead to template warnings or errors. Here are common issues and how to resolve them.

Missing or Broken Module References

If you see errors about missing modules after an upgrade:

• Confirm that all source modules are published.
• Check whether any nested modules were renamed or moved in the file tree.
• Update module references in the template or partials if paths changed.

Unexpected Layout Changes After Upgrade

Shifts in padding, alignment, or column behavior may occur if the nested module structure carried layout CSS. To address this:

• Compare the upgraded page to a pre-upgrade version if available.
• Inspect module div wrappers and classes in the design manager.
• Move layout-specific styles from retired nested modules into a parent module or stylesheet.

Fields Not Showing in Content Editor

If editors cannot see certain fields after you convert a nested module:

• Open the upgraded module in design manager.
• Confirm the field visibility settings.
• Check if any fields were set to Developer only or hidden in the content editor.
• Re-label fields to be clearer for non-technical users.

Best Practices for Hubspot Template Maintenance

Upgrading nested modules is part of broader template maintenance in Hubspot. To keep your system clean and scalable:

• Audit templates regularly for any remaining legacy nested modules.
• Document which modules are global and used across multiple templates.
• Use clear naming conventions for fields converted from nested modules.
• Test new modules on staging or clone templates before rolling them out to live pages.

Following these practices makes future upgrades smoother and reduces the risk of breaking live content.

Additional Hubspot Resources

For more technical details about upgrading nested modules, read the official Hubspot documentation on the topic here: Upgrade nested modules in the design manager.

If you need strategic help planning a larger design system refactor, you can also consult a specialized partner such as Consultevo to align your module architecture with long-term marketing goals.

By carefully converting legacy nested modules into modern structures and following consistent best practices, your Hubspot design manager environment will be easier to maintain, more intuitive for editors, and better prepared for future updates.

Need Help With Hubspot?

If you want expert help building, automating, or scaling your Hubspot , work with ConsultEvo, a team who has a decade of Hubspot experience.

Scale Hubspot

“`