Getting started with Hubspot Development

April 19, 2021

As a developer, Hubspot allows you to create Themes, Modules, Email templates, etc. Each of these different projects are initialized in the same way.

Unfortunately Hubspot’s documentation changes rapidly, and is mostly geared towards non-developers. So I wrote this guide to help you get up and running, building tools for Hubspot in no time!

1. Set up a developer account

First step is to make sure you have a Hubspot account. Head over to hubspot.com and set up an account if you don't already have one.

Next you need a developer account because Hubspot accounts only have one environment, and since you can’t run Hubspot code locally we need a personal developer account to serve as a dev environment.

Click this link to set one up.

2. Set up a local development pipeline

Now we're ready to start. Open up your terminal and/or favourite code editor. I'm assuming you have NPM installed. If not, find the instructions here.

2.1 Install the hubspot CLI tools

Run this command from your terminal.
npm install -g @hubspot/cli

If you need more help or it doesn't work follow these instructions.

2.2 Setting up your local environments

Run hs init to create a hubspot.config.yml. This file holds all your environment configurations, (similar to AWS credentials, if you've worked with AWS).

Run hs auth to populate your hubspot.config.yml with account information. This will bounce you out to the browser and back.
Make sure you name your environments strategically. These names are only for your local use, and are never used anywhere else.

Update your hubspot.config.yml so that the dev environment we set up above is used by default, this will make accidentally updating your production environment a lot less likely:

defaultPortal: DEV
portals:
 - name: PROD
   portalId: 123
   authType: personalaccesskey
   personalAccessKey: >-
     xxxxx-xxxxxx-xxxxxxx-xxxxxx-xxxxx-xxxxxxx-xxxxxxxx
   auth:
     tokenInfo:
       accessToken: >-
         xxxxx-xxxxxx-xxxxxxx-xxxxxx-xxxxx-xxxxxxx-xxxxxxxx
       expiresAt: '2020-01-01T00:00:00.000Z'
 - name: DEV
   portalId: 456
   authType: personalaccesskey
   personalAccessKey: >-
     xxxxx-xxxxxx-xxxxxxx-xxxxxx-xxxxx-xxxxxxx-xxxxxxxx
   auth:
     tokenInfo:
       accessToken: >-
         xxxxx-xxxxxx-xxxxxxx-xxxxxx-xxxxx-xxxxxxx-xxxxxxxx
       expiresAt: '2020-01-01T00:00:00.000Z'

When you work with a specific Hubspot account, make sure you add --account=dev or --portal=dev with the account name you want to target. As far as I can tell, --account and --portal are synonymous and can be used interchangeably.

3. The work process

Now everything is set up, and we’re ready to get to work. But first we need to talk about the process of how to work with Hubspot.

3.1 Using HS CLI to create things

Always start new themes or modules from the hs cli. There's a bunch of boilerplate and structural limitations that Hubspot changes over time, and you do not want track these manually.

Run hs create [type] [name] [dest] to create new items.
There are 7 different types of things you can create on Hubspot: function, module, template, website-theme, react-app, vue-app, and webpack-serverless.

The Hubspot cli tool always uses the hs [method] [source dir] [destination dir] format. The destination starts from the root of the account you're working with. See

for more.

3.2 Fetch, upload, and watch

When you're working with Hubspot, you need to use the Hubspot CLI tools to download and upload files to your account. There's no SSH, or FTP, and I'll talk about GIT later.

Hubspot uses some sort of version management system on their file system that we cannot access and they seem to have inherited an odd pairing of phrases from this:

hs fetch [source] [destination] will download the files from any directory in your account.

hs upload [source] [destination] will upload any directory to (and overwrite any files already present in) the destination directory.

hs watch [source] [destination] will listen to changes in your source folder and upload those files on save.

This is what you'll want to use while developing, and also the reason you need a personal dev environment.

Just remember that this watch doesn't do a diff or "upload changes since X". Initial files or batch changes will need to be uploaded using the above upload method.

3.x What about GIT pipelines?

If you've worked with other platforms you're probably wondering how the continuous integration pipeline works? How does Hubspot use modern pipelines like GitHub to version changes to prod? The answer is: it doesn't.

There's an official guide to setting up a GitHub action to run hs upload when your main branch is updated. But that's it. It works exactly like it would on a local machine.

I do recommend you set this up if you work with a team, since version management without CI opens the door to all sorts of issues. But it's not worth it in a one dev or two dev shop.

4. The Design Tools mess

Alright, we need to talk about one more thing.

Central to how code items (themes, modules, etc) in Hubspot work is the Design Tools. So called because it's the file manager and has nothing to do with design.

The design tools are probably where Hubspot originally thought developers would work, before they talked to any actual developers. It's a bit of a mess, and it doesn't follow common development patterns. Often mixing things like settings and config files.

This is where you can see all the files you upload to your hubspot account, in addition to all the defaults. Which is great.

When you create new items, like modules, this is also where you need to mark them as available so they can be used within Hubspot.

If you need to use third party files, like JS libs or fonts, you also need to upload them and then get a relative path to that file from the Design Manager to be able to reach the file from within your project. Even if the files are in the same directory.

And you can do all sorts of advanced settings and defaults in here.

Wrap up

That's it! Let me know if you have any additional questions or suggestions for how to improve this guide.