How to Create a HubSpot Theme Locally and Push It Live: A Step-by-Step Guide

HubSpot has become one of the most popular platforms for businesses looking to build professional, scalable, and conversion-driven websites. One of the key advantages of HubSpot CMS is the ability to create custom themes that align with your brand and business goals. In this comprehensive guide, we’ll walk you through how to create a HubSpot theme locally, make changes, and push it live to your HubSpot account. Whether you’re a developer or a marketer with basic technical knowledge, this step-by-step tutorial will help you manage your HubSpot themes efficiently.

Why Create a HubSpot Theme Locally?

Before diving into the steps, let’s discuss why developing a HubSpot theme locally is beneficial:

1. Faster Development – Working locally allows you to use your favorite code editor, manage files efficiently, and preview changes instantly.
2. Version Control – Local development enables the use of Git or other version control systems, making collaboration easier.
3. Error Handling – You can test your changes before uploading them to live HubSpot, reducing the risk of breaking the live site.
4. Scalability – Local themes allow you to structure your project for long-term maintenance, adding modules, templates, and assets easily.

Prerequisites

Before starting, ensure you have the following installed:

• Node.js and npm – Required for HubSpot CLI and package management.
• HubSpot CMS CLI – HubSpot’s command-line tool to manage themes and content.
• HubSpot Developer Account – Access to HubSpot CMS to upload your theme.
• Code Editor – Such as VS Code for editing theme files.

Step 1: Install HubSpot CMS CLI

To start, you need the HubSpot CLI installed on your local system. Open your command line or terminal and run:

npm install @hubspot/cms-cli -g

This command installs the HubSpot CMS CLI globally on your system, allowing you to run HubSpot commands from anywhere on your machine.

Step 2: Initialize HubSpot CLI

Once installed, initialize your HubSpot CLI with your HubSpot account key:

hs init

You will be prompted to enter your HubSpot API key. You can generate this key from your HubSpot developer account under Settings > Integrations > API Key. Once entered, the CLI will authenticate your account.

Step 3: Create a New HubSpot Project

Now, create a new local HubSpot theme project using the CLI:

npx @hubspot/create-cms-project theme-name

Replace theme-name with the name you want for your theme. This will create a folder with all the default HubSpot theme files, including:

• templates – For page templates
• modules – For custom modules
• css & js folders – For styling and scripts
• theme.json – The configuration file for your theme

You now have a local environment to build and customize your HubSpot theme.

Step 4: Upload Your Theme to HubSpot

Once your theme is ready or you have made changes locally, you can push it to HubSpot using:

hs cms upload mytheme theme-name

Here, mytheme is your local folder name, and theme-name is the destination folder on HubSpot CMS. After uploading, your theme will appear in your HubSpot account under Marketing > Files and Templates > Design Tools.

Step 5: Watch for Changes (Optional)

HubSpot CLI also allows you to watch for local changes and automatically sync them to HubSpot:

hs cms watch mytheme theme-name

This is especially useful during active development, as any edits you make locally are immediately updated on your HubSpot account, saving time and effort.

Step 6: Make Your Theme SEO-Friendly

After uploading your theme, ensure it is SEO optimized:

1. Meta Tags – Include proper meta titles, descriptions, and Open Graph tags.
2. Header Structure – Use H1, H2, and H3 tags appropriately for headings.
3. Alt Text for Images – Always add descriptive alt text for images.
4. Responsive Design – Ensure your theme is mobile-friendly.
5. Fast Loading – Optimize CSS and JavaScript files for performance.

Step 7: Update Your Theme

Anytime you make local changes, re-upload your theme using the same hs cms upload command, or use the hs cms watch command for continuous updates. This ensures your live site always reflects the latest version of your theme.

Tips for Efficient HubSpot Theme Development

• Use Partial Templates – Break your templates into reusable parts for faster editing.
• Custom Modules – Create flexible modules for content that can be used across multiple pages.
• Local Testing – Test locally using a HubSpot sandbox account to avoid affecting your live website.
• Version Control – Commit your changes to Git regularly to track edits.

🎥 Watch the Complete Tutorial Video

If you prefer learning through video, I’ve also created a step-by-step YouTube tutorial that walks you through the entire process of:

✔ Setting up HubSpot CLI
✔ Creating a theme locally
✔ Editing files on your local machine
✔ Connecting to HubSpot CMS
✔ Uploading & publishing your theme live
✔ Fixing common issues during deployment

👉 Watch the full tutorial here:

Conclusion

Creating a HubSpot theme locally and uploading it to your HubSpot account is a powerful workflow for developers and marketers. It gives you control over design, functionality, and SEO optimization while reducing risks on your live site. By following the steps above, you can efficiently manage your HubSpot themes, make real-time changes, and ensure your website is fully optimized for performance and search engines.

Start building your HubSpot theme locally today and experience faster development, better SEO, and scalable website management.