We just got our first theme approved on the HubSpot Template Marketplace. It's called Summit, it's free, and it's the same base theme we've been starting client sites from for a while now.
We'd published a few standalone modules before (baby steps), but a full theme is a different animal. Here's what my team and I learned along the way: how we found the time, what we put in, what tripped us up, and what we'd do differently. If you're thinking about submitting your own theme, I hope it saves you a few headaches.
1. Give internal projects real deadlines
We'd wanted to build a marketplace theme for years. Like most agencies, we'd get busy, and client work always won.
What finally worked was treating it like a client project. We set realistic deadlines, blocked out time when we knew we'd have it, and delegated pieces to the team. Whenever there was a gap in client work, Summit became the downtime priority. Instead of dreading the gaps, the team started looking forward to them.
2. Let the common features on your own projects decide what goes in
We didn't start from a blank page. We picked modules based on three things:
-
What we use most. The modules that have shown up again and again in our HubSpot builds over the past four years.
-
What clients ask for. The requests that keep coming up in proposals and retainers.
-
What marketing teams need. Summit is mostly for in-house marketers, so we leaned on easy-to-use presets they can edit without a developer.
The result is 13 page templates, 20 modules and 10 drag-and-drop sections.
3. Keep it simple, especially if it's free
We went back and forth on how much design and content to include, and how much to give away. We landed on a cleaner design and flexible modules, and skipped anything complex.
Part of that was practical. Summit is free, and every complex module is something we'd have to maintain. Simple turned out to have another upside, too. I think it made the review process smoother.
4. Build real sites with it before you release it
Before submitting, we used Summit as the base for a couple of client sites. Nothing shows you what's missing like building something real. Every rough edge we hit became a fix before launch.
If you don't have client projects to test on, install it in a test or sandbox account and build a few pages from scratch.
I kept one running list, split into three buckets:
-
Release blockers: must be fixed before submitting.
-
v1.1: improvements for the first update.
-
v2.0: bigger ideas for later.
That list kept us honest about what actually had to ship, and it gave us a ready-made roadmap the day we launched.
I also experimented with applying brand changes and building pages using the Claude connector together with the HubSpot CLI. It worked really well, and I'll be showing how in an upcoming webinar.
5. Use AI to check the requirements, but read the docs yourself
I used Claude to scan our repo against HubSpot's marketplace requirements. It's a huge time saver, with one big caveat: make it read the actual documentation, and read it yourself too.
I was chomping at the bit to get this out and skipped that step (yes, I know). Without the real docs in front of it, the AI filled the gaps with confident guesses:
-
It suggested we claim "inline help text on every module." Only 5 of our 20 modules had any.
-
It told me a feature didn't work when it actually did.
-
It suggested a listing name that broke HubSpot's naming rules.
Once it was working from the real requirements pages, the advice got much better. Treat AI like a fast junior teammate: great for the first pass, and someone needs to check its work.
6. Don't fully trust the validator
HubSpot's CLI has a marketplace-validate command, and you should run it often. But "no errors" doesn't mean you're ready:
-
It missed a missing file. It reported no errors for weeks while our licence file wasn't in the portal at all.
-
HubSpot drops settings it doesn't recognise. Use the wrong key name for a field and it simply disappears, with no warning. After uploading, fetch the files back and check what actually landed.
-
Deleting locally doesn't delete in HubSpot. Uploading adds and updates files but never removes them, so old files keep shipping to buyers unless you delete them in the portal too.
7. Read the rules nobody talks about
A few requirements caught us by surprise:
-
Free doesn't mean open source. We nearly put Summit under the MIT licence, until we realised it lets anyone resell or redistribute the theme. We went with a free licence that doesn't allow redistribution instead.
-
Check your image rights. Some stock licences, including Envato Elements, don't allow images to be redistributed inside a template, free or not. Ours were all from Unsplash, which does allow it.
-
The documentation has to be real. HubSpot requires a live page explaining how to set up and use the theme. An FAQ, contact page or homepage won't do.
-
Free themes have to be complete. No trial versions or locked features.
-
The small stuff counts: every system page, blog comments and author boxes, and a language switcher.
8. Don't put your agency name in the theme folder
Our theme started life as "Vaulted Summit". An innocent choice, and a really annoying one to undo.
When we renamed the theme folder, we found out that switching a page's template doesn't repoint the modules already on it. Every demo page kept pointing at the old theme, so we had to rebuild the whole demo site from scratch.
The Claude connector for HubSpot saved me a lot of the pain. With the base module content and a map of how each page was laid out, it rebuilt the pages for me. It was still a detour I'd rather not repeat.
It's also worth knowing that HubSpot doesn't allow your company name in the listing name either. Pick a theme name that stands on its own from day one.
9. What the review was actually like
I'd braced for a long list of fixes. We got two:
-
Module names. Two of our module labels included the theme name ("Summit Button" and "Summit Form"), which isn't allowed.
-
A missing language switcher. Even the best of us forget something.
There was one twist. The reviewer suggested renaming them to plain "Button" and "Form", but the validator rejects any label that matches one of HubSpot's own default modules. We went with "Styled Button" and "Form with Heading" and explained why in our reply.
After that, resubmitting and publishing was easy. Keeping the theme simple really did seem to make the review simpler.
10. Take screenshots and record the walkthrough last
We redid our screenshots several times. Every design tweak meant another round. Save yourself the trouble and capture everything right before you submit. (I still haven't recorded our walkthrough video, because I didn't want to record it twice.)
When you do capture them, watch for these:
-
Password manager icons. LastPass had dropped its little red icon into every form field in our captures.
-
Animations caught halfway. Our number counters count up as you scroll, so our first screenshots showed "16%" instead of "99%".
-
Image size limits. Figma caps images at 4096px, so very tall full-page captures come out slightly soft when you resize them.
11. Line up testers and a launch plan
Have a few people ready to download the theme as soon as it's live, try it, and give you honest feedback.
And don't leave promotion until the end. Plan these alongside the build:
Quick checklist before you submit
-
Theme and listing names don't include your company name
-
Module labels don't include the theme name, and don't match HubSpot's default modules
-
Built at least one real site with the theme
-
Read the marketplace requirements yourself, not just an AI summary
-
marketplace-validate passes, and you've checked the uploaded files in the portal
-
License allows free use without redistribution
-
Every image is licensed for redistribution
-
Live documentation page explains setup and use
-
Every system page, blog comments and author box, and a language switcher are included
-
Screenshots captured last, with no password manager icons or half-finished animations
-
Testers and launch content lined up
What's next
Building Summit was a great exercise in figuring out what makes a really good starter theme: what to include, what to leave out, and what makes it easy for someone else to pick up. We're already working through our v1.1 list, and we're excited to build more of these.
If you want to try it, Summit is free on the HubSpot Template Marketplace. And if you've been through the review process yourself, I'd love to hear what they flagged for you.
Matthew Deal
