Last modified: August 22, 2025
On HubSpot’s developer platform, you can use projects to create CMS content, such as themes and modules, using the HubSpot CLI. By building on the latest version of the platform, you can build with both React and HubL to take advantage of component composability, code reuse, broader community resources, and real access to JavaScript on the server at render time.
Below, learn about how to structure your project along with steps to build and deploy to your HubSpot account.
Prerequisites
- Because CMS React projects are developed locally, you’ll need to have the HubSpot CLI installed, along with Node v20.
- If you haven’t worked with CMS React projects before, it’s recommended to start with the quickstart guide.
Project structure
Your project structure will vary slightly based on whether your project includes a CMS theme or just React modules. Use the tabs below to view the basic project structure for theme or standalone React module development.
Below is the basic directory structure for a project with a CMS theme component on the latest version of the developer projects platform (2025.2).If you’re familiar with building classic HubL themes locally, it may be helpful to think of this structure as having two parts:
- The project-specific files and directories that enable you to build your theme on version
2025.2 of the developer platform. This includes everything from the project root folder to src/theme/ and the *-hsmeta.json file.
- The theme directory itself, which contains all of your theme assets and
theme.json configuration file. In the example structure below, this is the my-theme directory.
projectName/
├── hsproject.json
└── src/
└── theme/
├── theme-hsmeta.json
└── my-theme/
├── assets/
├── components/
├── styles/
├── templates/
├── fields.json
├── package.json
└── theme.json
| Name | Type | Description |
|---|
projectName | Directory | Top-level directory that contains all other project files. This directory can have any name, but must contain hsproject.json. |
hsproject.json | File | The project’s configuration file, which must be at the root of the project. |
src | Directory | The container for your project’s components. This directory can have any name as long as it’s specified in the hsproject.json configuration file at the root of the project. If your project also includes an app, the src folder would contain both a theme and app directory. |
theme | Directory | The directory that contains your theme directory and *-hsmeta.json configuration file. |
theme-hsmeta.json | File | The configuration file for the project’s theme component. |
my-theme | Directory | The directory containing the theme itself, including the theme.json configuration file and all theme assets (e.g., modules and templates). |
assets | Directory | The directory that contains supporting static assets, such as image files. Static assets with common extensions will resolve to public URLs automatically when used in modules. Learn more in Vite’s static asset documentation. |
components | Directory | The directory that contains the project’s islands and modules directories. |
styles | Directory | The directory containing the project’s stylesheets. |
theme.json | File | The theme configuration file, which includes fields such as the display label, screenshot path, version number, and more. Learn more about the theme.json file. |
package.json | File | The file used for loading scripts and third-party dependencies. |
Project schema
The *-hsmeta.json and .json schema requirements differ slightly based on whether your project includes a CMS theme or just React modules. Use the tabs below to view the basic project structure for theme or standalone React module development.
The top-level configuration file for your project’s theme component is specified in the theme-hsmeta.json file in the src/theme/ directory.my-project-folder/
└── src
└── theme/
└── theme-hsmeta.json/
{
"uid": "my-theme",
"type": "theme",
"config": {
"themePath": "my-theme",
"secretNames": []
}
}
| Field | Type | Description |
|---|
uid* | String | An internal unique identifier for the theme. Must be globally unique within the project. Can be any string up to 64 characters. Characters can be uppercase or lowercase, and can include numbers, underscores (_), dashes (-), and periods (.). |
type* | String | The type of component. Must match the name of the parent folder (theme). |
themePath* | String | The path of the directory containing the theme.json file and theme assets. |
Building and deploying
Using project-specific CLI commands, you can build and deploy your project to HubSpot. An hsproject.json file must be in the root directory of your project folder for the CLI to recognize your project.
To build and deploy your project, run hs project upload.
By default, projects are configured to auto-deploy successful builds. You can turn off auto-deploy in the project’s settings in HubSpot after initial upload. Projects with auto-deploy turned off can be deployed with the hs project deploy command.
View build and deploy history
In HubSpot, you can view your project’s build and deploy history as well as redeploy previous builds as needed.
To view project builds and deploys:
- Navigate to the project page in HubSpot:
- To open the project page from your terminal, run
hs project open from within the local project directory.
- Alternatively, in your HubSpot account, navigate to Development. Then, click the name of your project.
- On the Overview tab, you can view the most recent builds and deploys.
- Click the Builds & Deploys tab to view a full build and deploy history. To view more details about a particular build or deploy, click View details next to the build or deploy.
To turn off auto-deploy:
- Navigate to the project page in HubSpot:
- To open the project page from your terminal, run
hs project open from within the local project directory.
- Alternatively, in your HubSpot account, navigate to Development. Then, click the name of your project.
- Click the Settings tab, then toggle the Auto-deploy successful builds switch off.
Delete a project
To delete a project:
- Navigate to the project page in HubSpot:
- To open the project page from your terminal, run
hs project open from within the local project directory.
- Alternatively, in your HubSpot account, navigate to Development. Then, click the name of your project.
- On the project home page, click the Settings tab.
- At the bottom of the tab, click Delete.
- In the dialog box, enter the project name, then click Delete project.
