Last modified: August 22, 2025
CMS React modules are built using the developer projects framework, which enables you to build and deploy local code to HubSpot using the CLI. 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

Below is the directory structure for a basic CMS React project. 
project-folder/
│
├── js-package/
│   ├── assets/
│   ├── components/
│   │   ├── islands/
│   │   └── modules/
│   ├── styles/
│   ├── cms-assets.json
│   └── package.json
│
├── … optionally other project components …
│
└── hsproject.json
NameTypeDescription
project-folderDirectoryTop-level directory that contains all other project files. This directory can have any name, but must contain hsproject.json.
hsproject.jsonFileThe project’s configuration file. Must be at the root of the project in order for hs project upload to recognize your project.
js-packageDirectoryThe directory that contains your React assets along with the cms-assets.json file. This directory can have any name.
assetsDirectoryThe 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.
componentsDirectoryThe directory that contains the project’s islands and modules directories.
islandsDirectoryThe directory that contains the project’s island files. Learn more about islands.
modulesDirectoryThe directory that contains the project’s module directories and files. Learn more about modules.
stylesDirectoryThe directory containing the project’s stylesheets.
cms-assets.jsonFileMust be contained within the JavaScript asset package subfolder in order for your React components to build properly.
package.jsonFileThe file used for loading scripts and third-party dependencies.
In the above example project structure, note that there’s an optional space for other project components. One example of another project component you might add is a private app for running serverless functions. In that case, you would include an app directory with the following structure: 
project-folder/
│
├── js-package/
│   ├── assets/
│   ├── components/
│   │   ├── islands/
│   │   └── modules/
│   ├── styles/
│   ├── cms-assets.json
│   └── package.json
│
├── app
│   ├── app.json
│   ├── app.functions/
│   │   ├── function.js
│   │   └── serverless.json
└── hsproject.json
Learn more about serverless functions, and check out HubSpot’s example CMS React serverless project to see an example of implementation.

​
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. 
hs project upload
Please note: HubL assets, such as HubL templates that reference React modules, aren’t managed by the projects system and need to be uploaded with hs upload instead.
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. To turn off auto-deploy: 
hs project open
  • From the project settings page, click the Settings tab, then toggle the Auto-deploy successful builds switch off.
project-auto-deploy-setting

​
View project activity

On the project settings page in HubSpot, you can view build and deploy history to view code changes and redeploy previous versions if needed. To view project activity:
project-details-tab
  • Click the Activity tab to view all project build and deploy history. You can use the buttons above the activity table to filter by All activity, Builds, and Deploys.
  • To view more details about a particular build or deploy, click View details next to the build or deploy.
project-activity-tab
  • When viewing details for a build:
    • Use the left pane to explore the files uploaded as a part of the build. Files that have been changed since the previous build will be highlighted in yellow. You can select a file to view its contents at build time in the right pane.
    • Use the right pane to view the build logs and file contents for a selected file.
  • To deploy a previous build, click Deploy this build in the upper right.
project-build-details

​
Delete a project

To delete a project:
project-delete
  • In the dialog box, enter the project name, then click Delete project.