Getting started with Hubspot Development
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.