HubSpot Custom Modules: The Guide to Building Pieces Marketing Can Edit on Its Own

There is a classic symptom of a poorly built HubSpot site, and you might recognize it. Every time marketing wants to change a piece of text, adjust an image, or reorder some cards, someone has to call the developer. The content team is held hostage by whoever codes, and the developer becomes a bottleneck for changes that should take two minutes.

The cause is almost always the same: poorly built modules. A good custom module is a reusable, lightweight, easy-to-edit piece that gives marketing autonomy within safe limits. A bad one is a rigid block, tied to a single page, that only the developer understands. In this guide, I will show you how to build the first kind: a module's structure, field types, repeater fields, and the best practices for reuse and performance.

What a custom module is

In HubSpot Content Hub, modules are the pieces marketing drags into a page or template to build content. A hero banner, a testimonials section, a strip of client logos: each of these is a module. They are the building unit of the site, and their quality defines how much the team can run the site without technical help.

The point of a module is to separate structure from content. The developer defines how the piece behaves and looks, and exposes to marketing only the fields that make sense to vary, like the title and the image. That way, content changes without the layout breaking. This separation is the heart of a sustainable site on HubSpot.

The anatomy of a module

Each module is a folder with the .module extension and three core files that talk to each other. Understanding the role of each is the first step to building good modules.

• module.html: the HubL template and the piece's HTML. This is where the defined fields actually become the content that appears on screen.
• fields.json: the definition of the editable fields, that is, everything marketing sees and can change in the visual editor.
• meta.json: the module metadata, like the label shown in the editor, the icon, and which template types it can be used in.

The piece's CSS and JavaScript live in their own files, module.css and module.js, and HubSpot loads them only when the module is present on the page, and only once even if the module appears several times. This on-demand loading is an important performance detail, because it keeps a piece's style and script from weighing on pages where it does not even appear.

Fields: give control without giving chaos

Field types cover text, rich text, image, link, color, choice, and groups. The secret of a good module is balance: expose what needs to vary and lock the rest. Expose the title, the image, and the button link, but keep spacing, behavior, and alignment fixed in the template. That way marketing edits content freely without ever breaking the layout.

The most common mistake here is exposing too many fields, in the illusion of giving flexibility. When marketing can change spacing, background color, font size, and ten other things per piece, each page ends up with a different look, and the site's identity is lost. Fewer, well-chosen fields create more consistency and less support.

Repeater fields for lists

When the module shows a list of identical items, like several testimonials, cards, or logos, the right tool is the repeating group field. Instead of creating ten fixed fields for ten cards, you create a repeating group, and marketing adds or removes items at will. The template loops over all of them, generating each one's HTML automatically.

This completely changes the experience for whoever edits. With fixed fields, adding a card requires the developer. With a repeater, marketing does it alone, on the spot. It is the difference between a module that ages poorly, always needing technical adjustment, and one that grows with the content without friction.

Reuse: the secret of a sustainable theme

A generic, well-named module is used on many pages. A module tied to a specific page is used once and forgotten. The difference between the two defines whether your theme becomes a lean library of reusable pieces or a bloated collection of single-use blocks nobody understands anymore.

When creating a module, ask: could this piece serve on other pages? If so, generalize the name and fields so it does. A content module split into text and image, for example, works on a service page, an about page, and a landing page. Investing in generic pieces is investing in the site's cheap long-term maintenance.

Performance and versioning

Each module loads its CSS and JS, and heavy pieces add to the load time of the pages where they appear. Keep the style and script lean, avoid large libraries for simple effects, and remember that page speed affects both ranking and conversion. A fast site starts with lightweight modules.

And treat the module files as real code, because they are. Changes should go through review before reaching production, not be edited straight on the live site. A module is reused across many pages, so an error in it multiplies. Versioning and reviewing is what keeps a small adjustment from breaking the whole site at once.

Why this matters for your operation

Well-built modules are not just a technical matter, they are a matter of business speed. A marketing team that can launch a landing page, adjust a section, or swap a testimonial on its own, without queuing with the developer, is a team that moves at campaign speed, not at the technical backlog's speed. The autonomy a good module gives translates directly into more content live, faster.

On the other side, bad modules create an invisible bottleneck that costs dearly. Each simple change becomes a ticket, each ticket enters a queue, and campaign ideas die waiting for a change that should be trivial. Investing in well-designed modules is, at heart, investing in the whole company's marketing agility.

In practice: the site that depended on the developer for everything

A company had a HubSpot site where each page was a single, giant module, with all the content hardcoded. To change one sentence on the home page, marketing opened a ticket, and the adjustment took days in the technical team's queue. The frustration ran both ways: marketing stuck, the developer drowning in micro-tasks.

The rebuild was to break those giant blocks into generic, reusable modules, with well-chosen editable fields and repeaters for the lists. After that, marketing started building and adjusting pages on its own, and the developer went back to focusing on what only they could do. The same site, with the right structure, stopped being a bottleneck and became a tool.

Checklist of a well-built module

1. Does the piece have the three core files, module.html, fields.json, and meta.json?
2. Do the fields expose what needs to vary and lock what needs to be consistent?
3. Do lists of items use a repeating group field, not fixed fields?
4. Are the CSS and JS in their own lean files, loaded on demand?
5. Is the module generic and well-named, designed for reuse across pages?
6. Do changes go through review before reaching production?

Frequently asked questions

What is the difference between module.html and fields.json?

fields.json defines the fields marketing edits in the visual editor. module.html uses those fields in HubL to generate the final HTML that appears on the page. One declares the fields, the other renders them.

When should I use a repeater field?

Whenever the module displays a list of identical items, like cards, testimonials, or logos. The repeater lets marketing add and remove items without touching code or calling the developer.

Why separate CSS and JS into module files?

Because that way they load only when the module is present on the page, instead of weighing on every page. This on-demand loading helps site performance.

How many fields should a module have?

The minimum that gives control over what needs to vary. Exposing too many fields, like spacing and color per piece, makes each page different and breaks the site's identity. Fewer well-chosen fields create more consistency.

Can I reuse the same module on different pages?

Yes, and that is the goal of a well-built module. A generic, well-named piece works on many pages, which keeps the theme lean and maintenance cheap.

Does a custom module require knowing how to code?

Creating the module requires knowledge of HubL, HTML, and CSS. But once created, it is edited by marketing in the visual editor, with no code. That is exactly the value of a module: code it once for the team to use forever.

Want modules your marketing team can edit on its own, without breaking the layout or slowing the site? At Insight Sales, as a HubSpot partner, we develop custom themes and modules. Talk to our team and find out how we can help.