Local Development Tooling [BETA]: Getting Started
The beta Local Development Tooling connects your local workflow to HubSpot, allowing you to utilize version control, your favorite text editor and various web development technologies when developing on the HubSpot CMS.
In this guide, we'll walk through installing the basics, fetching a project from your HubSpot account, and then sync changes back to your Design Tools. To get the most out of this workflow, you'll need some working knowledge of the Command Line. For more commands and local file formats, see the Local Development Tooling Reference.
ℹ️ Did you know you can use free CMS developer sandbox accounts as development environments? Create one now by clicking "Create an Account", selecting your user, and opting to "Create a new, fresh account" here. ℹ️
To use the local tooling, you'll need to:
- To install the HubSpot tools globally, run npm install -g @hubspot/cms-cli in your command line. To install the tools in your current directory, run npm install @hubspot/cms-cli.
Create a working directory
Create a folder for your local project. For example, run mkdir local-cms-dev in the command line, which will create a directory. Then, run cd local-cms-dev to navigate to that directory.
Set up your configuration file
When you run commands in the local tools, the tools reference this file to authenticate your HubSpot account access. This file may live in a higher level directory than your project files. There are two methods you can use to set up your hubspot.config.yml file which contains your authentication credentials.
Use guided configuration(recommended)
In the terminal in your new directory run
hs init then follow the prompts to set up the authentication for your local environment to be able to interact with your HubSpot account.
You will be prompted to choose an authentication method, API key or OAuth. We generally recommend OAuth as it is more secure.
- You will be asked to enter a name for your Hub - this name is a local-only nickname for the HubSpot account to make it easy to reference when using the tools.
- Next you will be asked for a Hub ID, this is the account you wish to modify files in.
- Enter your API key
- You will need to create a private developer app. NOTE: You must select the "Content" scope, and have all Marketing permissions in your account with the CMS.
- When prompted enter your CMS Hub id.
- Enter your client id and and client secret from your private developer app. This will open a window in your default browser requesting authorization. Select your account with the CMS on the authorization page.
- Your private app will request permission to access your account data. Click "Grant Access".
If successful, you should see "Authorization Succeeded", and your hubspot.config.yml file will be updated. Proceed to the next step.
In your new directory, run touch hubspot.config.yml to create a hubspot.config.yml file.
There are two ways that you can authenticate with HubSpot in your local development environment.
- OAuth2 (more secure)
- Create a private developer app. NOTE: You must select the "Content" scope, and have all Marketing permissions in your CMS portal.
- Run npx hs auth oauth2 in the command line. This will begin a series of command line prompts.
- Enter your Hub id for the portal with the CMS.
- Enter your client id and client secret from your private developer app. This will open a window in your default browser requesting authorization.
- Select your CMS hub on the authorization page.
- Your private app will request integration permissions to access your account data. Click "Grant Access".
- If successful, you should see "Authorization Succeeded", and your hubspot.config.yml file will be updated.
- HubSpot API Key
- Set up an API key for the HubSpot account.
- Add an entry in the config file.
Your hubspot.config.yml will look something like this:
defaultPortal: 'DEV' portals: # Sample apikey entry, manually entered - name: 'DEV' portalId: 123 authType: 'apikey' apiKey: 'xxxxxx-xxxxx-xxxxx-xxxxx-xxxxx' # Sample oauth2 entry, generated from running npx hscms auth oauth2 - name: 'PROD' portalId: 345 authType: oauth2 auth: clientId: xxx-xxx-xxx-xxx clientSecret: xxx-xxx-xxx-xxx scopes: - content tokenInfo: expiresAt: '2019-07-01T16:42:44.311Z' refreshToken: xxx-xxx-xxx-xxx accessToken: >- xxx-xxx-xxx-xxx-xxx-xxx-xxx-xxx-xxx-xxx-xxx-xxx-xxx-xxx-xxx-xxx
In the above example, you'll notice multiple entries are supported in the hubspot.config.yml file. You can optionally add a name to an account entry. When running commands, either name or portalId can be used in the --portal= option (ex. --portal=123 and --portal=DEV will both interact with account ID 123 based on the above example). If you set a top-level defaultPortal, you can exclude the --portal= option from your commands, but commands will reference that default portal.
Fetch a project from your account
Using the fetch command, run npx hs fetch --portal=<name> <src> <dest> to get an entire projects folder tree and files from your HubSpot account into your local environment. The src is the project path in your HubSpot Design Tools, and the dest is the path to the local directory you would like the files to be placed, relative to your current working directory. To fetch the project to your current working directory, you can leave out the <dest> argument.
Here is an example of how you would fetch a project from your HubSpot account:
local-cms-dev $ npx hs fetch --portal=DEV cms-project
This is the Design Tools project we fetched to our local environment:
Make changes and sync to your HubSpot account
Using the upload command, run npx hs upload --portal=<name> <src> <dest> to upload the project in your local environment to your HubSpot account. This will copy the contents of the <src> and upload them to your HubSpot account in the <dest>. If you're creating a new project in your Design Tools, the <dest> can be a net new folder in HubSpot.
Here is an example of how you would upload the example project into your HubSpot account:
local-cms-dev $ npx hs upload --mode=draft cms-project cms-project
This uploads a draft version of your changes, so you can preview them in the design tools. If you'd prefer to publish your changes from this sync command, use --mode=publish, or omit the --mode option.
Watch your local project and automatically upload changes
Run npx hs watch --portal=<name> <src> <dest> to watch your local directory and automatically upload changes to your HubSpot account on file saves.
Here is an example of how you would run that command with the watch command:
local-cms-dev $ npx hs watch --mode=draft cms-project cms-project
For more commands, see the Local Development Tooling Reference.