Last modified: August 22, 2025
Using HubSpot’s developer projects framework, you can build a CMS theme locally, then deploy it to your HubSpot account. This method of theme development has a few advantages over the classic method of developing a HubSpot theme:
  • Themes built using this method can include React-based modules.
  • By building with a project, you’ll be able to use HubSpot’s build and deploy pipeline for better version control.
By the end of this tutorial, you will have:
  • Used the HubSpot CLI to set up your local environment for development.
  • Uploaded a boilerplate theme and project to your account.
  • Viewed the project and theme in HubSpot.

​
Prerequisites

Before getting started, you’ll need to create a HubSpot account (any subscription, including a free account). It’s recommended to sign up for a CMS Sandbox account, where you can create test accounts for safer iteration. It’s also recommended to have a basic familiarity with the following:
  • HTML, HubL, and React. Some knowledge of TypeScript may also be helpful.
  • Using the command line to run commands locally. When developing locally with HubSpot, you’ll use the HubSpot CLI, which this guide will walk through installing.
1

Run the setup script

Because you’ll be developing the theme locally then uploading it to your account, you’ll first need to set up your local development environment. To speed up this process, HubSpot provides a script that you can run from the command line to handle basic setup tasks, including:
  • Generating a JavaScript-based HubSpot theme
  • Installing the latest version of the HubSpot CLI if not already installed
  • Installing all necessary dependencies
  • Authenticating with your HubSpot account to connect it to the HubSpot CLI
To get started:
  • Create a local directory where you’ll be storing your project, or decide on an existing directory to use (e.g., Dev/Themes/newProject). Then, using the command line, navigate into the directory using the cd command.
cd ~/path/of/working-directory
  • Run the setup script.
npx @hubspot/create-cms-theme@latest
  • Follow the prompts in your terminal to proceed through the setup.
During the authentication step, the terminal will prompt you to open the personal access key of your HubSpot account.
  • If you’ve already connected your HubSpot account using hs account auth, this step will be skipped. If you want to connect additional accounts to the HubSpot CLI, you can run hs auth after the setup script is complete.
  • To create a new personal access key:
    • In the browser, ensure all permissions checkboxes are selected.
personal-access-key-permissions
  • Click Generate personal access key.
  • In the Personal Access Key section, click Show, then Copy, then paste your key into the terminal.
  • Continue following the prompts to finish authenticating.
After authentication is completed, a ~/.hscli/config.yml file will be created in your home directory, and will look similar to the example below:
defaultAccount: account-name
portals:
  - name: account-name
    accountId: 1234567
    env: prod
    authType: personalaccesskey
    auth:
      tokenInfo:
        accessToken: >-
          <accessTokenValue>
        expiresAt: '2025-02-13T15:44:59.399Z'
    accountType: STANDARD
    personalAccessKey: >-
      <personalAccessKeyValue>
After authenticating, you should see a message in your terminal confirming that your starter theme was created successfully. Your working directory should now also contain a theme directory with the following structure:
my-cms-theme/
│── node_modules/
├── src/theme/
│   ├── assets/
│   ├── components/
│   │   └── modules/
│   ├── node_modules/
│   ├── styles/
│   ├── templates/
│   ├── fields.json
│   ├── Globals.d.ts
│   ├── package.json
│   ├── theme.json
│   └── tsconfig.json
│── .prettierrc
│── hsproject.json
└── package.json
2

Preview theme assets locally

Start a local development server to view the theme locally before uploading to HubSpot.
  • In the terminal, navigate into the theme directory that was created by the setup script.
cd my-cms-theme
  • Start the local development server with the npm run start command.
npm run start
After the local development server starts, the terminal will provide a URL to open in your browser (http://hslocal.net:3000).
HubSpot CMS dev server hosting: your_directory/theme (at http://hslocal.net:3000, hubid=<yourHubId>)
  • Open the URL in the browser to view the local development server page.
CMS local development server page
At the top of the page, you can view a summary of the assets that are available to preview in your project. For this example, you’ll see one module listed.
  • To quickly view the details of a module, including its local path and fields.json code, click the name of the module, then review its details in the right sidebar.
The module name highlighted to show what to click to view a module's details
  • To preview the module, click View local version. A new browser tab will open containing a preview of the module.
The View local version button highlighted
With the local development server running, the local version preview will automatically update when you save code changes. As an example, make a change to the module’s styling and view how it updates the module preview:
  • In your local editor, open the getting-started.module.css file in /src/theme/styles.
  • Note that the .wrapper declaration block contains a background-color rule with a value of var(--accent-color). This is the rule you’ll need to update in order to change the module’s background color.
  • In the :root declaration block at the top of the file, add a new custom color variable of --custom-color:#5e6ab8.
:root {
  --primary-color: #ff7a59;
  --accent-color: #2d3e50;
  --custom-color: #5e6ab8;
}
  • In the .wrapper declaration block, update the background-color rule to use the new color variable.
background-color: var(--custom-color);
  • With the module preview open, save your changes. On save, the browser will automatically refresh and display your updated styling.
gettingstarted-module-after-styling-update
3

Upload to HubSpot

Upload your local theme to HubSpot to make it available for content creators. After uploading, you’ll also be able to access all of the project’s assets in a centralized projects UI in HubSpot, where you can view build and deploy history, review logs, and more.To upload your theme, run hs project upload.
hs project upload
After the project builds and deploys to your account, the terminal will confirm that the project has been successfully uploaded. Note that, by default, HubSpot auto-deploys projects after a successful build. You can turn this off in the project settings in HubSpot if you’d prefer to manually deploy with the hs project deploy command.
4

View the project in HubSpot

With your project and theme uploaded to the account, open the project in HubSpot to view its initial build and deploy history and familiarize yourself with the projects UI.
  • To navigate to your project in HubSpot using the command line, run the hs project open command in your terminal.
hs project open
The project settings page will then open in your browser.
You can also get to this page in your account by navigating to CRM Development in the main navigation bar, then selecting Projects in the left sidebar. Then, click the name of the project.
  • On the Details tab, view an overview of the current state of the project as well as most recent activity.
cms-starter-theme-project-view
  • On the Activity tab, view a full history of builds and deploys. You can click View details to see more information about each activity.
project-ui-activity-tab
  • On the Settings tab, you can manage project settings such as auto-deploy and GitHub repository linking, as well as delete the project.
project-ui-settings-tab
5

Create a page

To create a page using your newly uploaded custom theme:
  • In your HubSpot account, navigate to Content > Website Pages.
  • If you’re working in a new account:
    • Click Start from scratch, then locate the theme that you just uploaded and click Set as active theme.
    • Next to the Getting started with CMS React template, click Select template.
choose-a-template
  • If you’re working in an existing account with a theme already selected:
    • In the upper right, click Create.
    • In the dialog box, enter a name for the page, then click Create page.
    • On the Choose a template page, click the Theme dropdown menu, then select Change theme.
change-theme-dropdown-menu
  • Locate the theme you just uploaded, then click Set as active theme.
  • Next to the Getting started with CMS React template, click Select template.
choose-a-template
You’ll then be brought to the page editor where you can continue editing the page content before publishing the page.

​
Next steps

Having successfully uploaded the starter theme to your account, you can continue to make changes locally, then build and deploy using the hs project upload command. To learn more about developing on HubSpot’s CMS, you may want to check out some of the following resources: