Create a project (BETA)

  • Sales Hub
    • Enterprise
  • Service Hub
    • Enterprise

Using projects, you can package, build, and deploy private apps to HubSpot locally using the CLI. The private app can contain UI extensions to customize your CRM with custom cards across various CRM records. Once deployed to HubSpot, you can view the project within the account to see its build and deploy history, manage its settings, and monitor the private app’s usage. 

This guide walks through how to create a project from scratch. After creating and uploading the project, you'll then create a private app within it, followed by a custom card UI extension. Before continuing with this guide, ensure you’ve set up your local environment and created a development sandbox, if needed.

To get started developing a project, app, and UI extension from a template, check out the quickstart guide instead. You can also view example projects that contain private apps and UI extensions in HubSpot's example extension library on GitHub.

Create a project

To create a project from scratch:

  • In the terminal, navigate to the folder where you'll be storing the project locally. A project can live anywhere locally, but will be stored in HubSpot as a root-level directory in the developer file system.
  • Run hs project create.
  • Enter a name for your project, then hit Enter.
  • Hit Enter to create the project in the current directory. Or enter a new directory path, then hit Enter.
  • Hit Enter to create a project with no template. You can learn more about the Getting Started template in the quickstart guide

A project directory will then be created with the following assets:

  • An hsproject.json file in the root directory to configure the project.
// example hsproject.json file { "name": "my_project", "srcDir": "src" }
  • An src folder where you'll build your private app. This folder can have any name as long as it matches the srcDir value in the hsproject.json file. 


Next, upload the project to HubSpot by running hs project upload. This will upload the empty project to your account where you can then view it.

Please note: if you encounter a Project config not found error, ensure that you're the root directory of the project, which contains the hsproject.json file.

View the project in HubSpot

To view your deployed project in HubSpot:

  • In your HubSpot account, navigate to CRM Development.
  • In the left sidebar menu, navigate to Projects. The project card will display a This project is empty message, which is expected because you've uploaded a project without a private app.
  • Click the name of the project. The project details page will display information about build history once a private app is added to the project.

From the project details page, you can also manage auto-deploy settings:

  • On the project page, click the Settings tab.
  • Click to toggle the Auto-deploy successful builds switch off. 


Next, create a private app in the project to start building out the project's functionality.

Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.