How to Set Up Local Development with HubSpot

Designing and developing in the HubSpot CMS is great, but if you want the option of developing in a local environment, HubSpot now has that option!

What is local development? local development environment allows you to setup a server environment on your own machine, instead of using the server environment provided by the HubSpot CMS. This allows you to customize your site without worry that'll it'll break, and make all kinds of changes, before pushing your site online.


Let's say you want to build apps in HubSpot but find it much more efficient to develop you applications locally. Developing locally allows you to utilize version control through Github, and in addition to that, lets you develop in your favorite code editor! (I use VS Code)


Let's take a look at how to set that up - keep in mind that this post will assume you have a basic working knowledge of development in general, and are familiar with the command line. If you need a refresher or want to start from the ground up, here's some material to help get you up to speed.

Local Environment Setup

First before we get started you have to make sure you have Nodejs installed on your machine. Nodejs is a Javascript runtime environment and is what we will use to install most of what we need. 


Now we need to install HubSpot tools globally - open the command line and run:

       -     npm install -g @hubspot/cms-cli


Then, make a folder for your local project with the command line and cd into it :

- mkdir local-dev-hubspot

- cd local-dev-hubspot

HubSpot Configuration

Now we need to set up a configuration file. When we run commands locally, you will need this file to authenticate your HubSpot account access. This file will contain your authentication credentials. The most secure way to implement local development is through Oauth2, which is much more in-depth than the way we will be setting this up. The less involved (less secure) way of doing things is with an API key. In the earliest days of modern web APIs, the API key was all we had. It likely remains as the most common identifier, and is the first many developers consider when restricting or tracking API traffic. The best thing about an API key is its simplicity.  Use OAuth access tokens if you want users to easily provide authorization to applications without needing to share private data or dig through developer documentation.


To get our key, in the terminal in our new directory, run:  hs init, follow the prompts and when asked about your authentication method choose API key. You will be asked to enter a name for your Hub - this name is a local-only nickname for the HubSpot account. Next you will be asked for a Hub ID, this is the account you wish to modify files in. Finally, you will have to enter your API key.


For manual configuration, we will have to create a file called hubspot.config.yml. For an explanation of what a yaml file is check this out.


Here is what you .yml file should look like:

defaultPortal: 'DEV'


 # Sample apikey entry, manually entered

  - name: 'DEV'   

 portalId: 123    

authType: 'apikey'   

 apiKey: 'xxxxxx-xxxxx-xxxxx-xxxxx-xxxxx'     


You can name your defaultPortal whatever you like, the command to use when “fetching” your files from HubSpot, making changes and syncing to your HubSpot account or just watching your local project and automatically upload changes are:

npx hs fetch --portal=DEV   cms-project

npx hs upload --mode=draft cms-project cms-project

npx hs watch --mode=draft cms-project cms-project


That’s it!! Congratulations you will now be able to develop locally with HubSpot!

HubSpot Website Design Impact Award Winner