About us

Getting started: CMS React for HubSpot developers

last updated on

Developer Garden

This article seeds a growing collection of interconnected articles, code examples, and step-by-step guides. Check back soon as this and other articles branch out.

The Getting Started Example from the official CMS React Github repo is the best introduction to HubSpot's shiny new . We'll walk through the steps to get the example up and running and see how it all fits together.

If you're comfortable with HubSpot development but new to React, this article is for you. React in HubSpot unlocks a new world of possibilities!

We won't spend much time reviewing React code in this article. Instead, we'll focus on just the setup and how the HubSpot and React parts work together.

Prerequisites

React CMS works with all levels of HubSpot CMS from free to Enterprise. Some advanced features are limited to Pro and Enterprise but as a developer you have full access using a free developer account.

If you don't have a HubSpot developer account yet, you should sign up for one.

Cloning from the Github repo

Navigate to a folder where you keep code and clone the repo using the command below:

Code
1
git clone https://github.com/HubSpot/cms-react.git

The repo contains other resources and many examples so we'll have to navigate to the getting-started example.

Code
1
cd cms-react/examples/getting-started

Before we do anything else, let's take a look at the folder structure and contents of the getting-started example. I reversed the order of directories a bit so that you can see the familiar theme and root structure first.

Code
123456789101112
.
├── getting-started-theme
│   ├── (nothing new here)
│   └── ...
├── package.json
├── hubspot.config.yml
├── getting-started-project
│   ├── hsproject.json
│   └── getting-started-app
│       ├── package.json
│       └── ... (all React code)
│   ...

Conceptually, the "Getting Started Example" is split into two groups:

The HubL Theme

No surprises here. The root directory and the theme directory are exactly the same as your regular HubSpot local development setup. When you add CMS React to your existing themes you won't need to change a thing.

  1. / is the root of the project. This is where your local development tooling is located and contains things like your package.json, ESLint, Prettier, etc.

  2. /getting-started-theme is the HubSpot Themes folder you know and love. This is where your regular theme code lives: templates, modules, styles, etc.

The React Project

React CMS uses HubSpot's Projects system. For our purposes here, it's just a folder. When you add React outside of this example, you'll only need to create a new folder and follow the same structure.

  1. /getting-started-project is the folder the HubSpot Projects system uses to build and deploy your react code. The hsproject.json file is the configuration file for the project.

  2. /getting-started-project/getting-started-app is where your react code actually lives. Everything React-specific is here: components, modules, islands, tooling, etc.

Install dependencies

From the root directory, run the following command to install dependencies:

Code
1
npm install

The "Getting Started Example" helpfully contains a postinstall script that installs React dependencies for you.

It's important to understand that you are installing both sets of dependencies. Without the postinstall script you would have to run npm install in the root directory and then npm install again in the /getting-started-project/getting-started-app directory.

The HubL Theme and React Project have their own dependencies but some are shared — e.g., the HubSpot CLI is used for both.

a common bug

You might have accidentally installed multiple version of the CLI or have it installed in both directories — the error messages when this happens are not great. To avoid future bugs, uninstall the existing CLI. First run npm uninstall @hubspot/cli in the root directory and then run the same command in the getting-started-app directory. Finally, run npm install -g @hubspot/cli to install it globally.

Upload the HubL Theme

This is all standard local development stuff. Run hs init from your root directly and follow the prompts to authenticate your account and autogenerate a hubspot.config.yml file.

Then run the following command to upload the theme to HubSpot:

Code
1
npm run upload:hubl

Running this command uploads the "Getting Started" theme to your HubSpot account and a template page named "Getting Started - Weather Forecast".

Deploy the React Project

To really give you the full experience, the example includes making a request to the OpenWeather API to display the weather forecast. You'll need to get an API key from OpenWeather and add it to the .utils.ts file in the /getting-started-project/getting-started-app directory.

Look for this line and replace with your API key:

utils.ts
1
const apiKey = "<YOUR_API_KEY>";

Finally, we can deploy to HubSpot's Project system. Run the following command from the root directory:

Code
1
npm run deploy

This command builds the React project and deploys it to the HubSpot Project system. Deployed modules and partials become available in templates and modules in the HubL Theme.

If you've followed all of the previous steps you should now be able to create a new page from the "getting-started" theme and see a weather module!

The fun part - live proxy previews

Previous steps were all about getting the example up and running. Now we can explore one of the best parts of React CMS — the ability to make local changes and see them reflected in a live proxied version of a published page or preview.

Here's how to do it:

  1. From your root directly, run npm start. This command starts a local development server. Check package.json to see the command in full (it eventually leads to npm start in the React CMS app directory)

  2. Open the "Getting Started - Weather Forecast" page in your browser — either as a preview or as a published page. You should see the weather module.

  3. Click the HubSpot "Sprocket" icon in the top right corner of the page and select "Open Local Dev Sever".

  4. Now when you make code changes in the React project, you'll see them reflected in the live preview. Try changing a heading or some text.

The live proxy preview is an amazing way to work with all of the context of a live page without having to deploy each time.

Future articles will include a public Github repo with all sample code and a branched starting point — we'll let HubSpot handle the heavy lifting for this one.

If you have any questions or need help, reach out in the HubSpot Developer Slack #cms-react channel.

Links and sources that helped craft this article