HubSpot projects overview (BETA)

Using projects, you can package, build, and deploy private apps to HubSpot locally using the CLI. Through private apps, you can customize your CRM with custom cards across various CRM records. You can also include serverless functions within the app to write server-side JavaScript that runs on HubSpot, meaning you don't need to manage a server to interact with data within and outside of HubSpot. Once deployed to HubSpot, you can view the project within HubSpot to see its build and deploy history, manage its settings, and view the private app and its components. 

In this guide, learn more about the anatomy of a project and how to manage it in HubSpot once deployed.

To get started developing a project, review the setup guide to get your local environment setup, including creating a development sandbox, then walk through the quickstart guide.

To view example projects that contain CRM cards, check out HubSpot's example extension library on GitHub.

Project components

Below, learn more about the various elements that can be included in a project.

Private apps

Private apps contain components such as extensions and custom objects, and enable you to access HubSpot data more securely than using an API key. Using serverless functions, you can customize the functionality your project components, such as CRM cards, by interacting with HubSpot data as well as external data. A project can contain multiple apps, and an app can contain multiple extensions and asset definition files.

Extensions

Extensions include CRM cards and can expand the functionality of your HubSpot account by surfacing custom UI and actions to users. In a project, extensions live within private apps.

For example, create a CRM card to track bugs logged in external software such as Jira directly on CRM records.

Learn more about creating CRM cards with projects.

Serverless functions

Serverless functions allow you to write server-side JavaScript that runs on HubSpot. You can manage serverless functions in your local development tools and in HubSpot’s design manager. Serverless functions live within the private apps folder and provide functionality to apps and extensions.

Learn more about creating serverless functions with projects.

Project file structure

A project can live anywhere locally, but will be stored in HubSpot as a root-level directory in the developer file system. A project is required to have the following structure for it to successfully build and deploy:

  • An hsproject.json file in the root directory to configure the project.
  • An src directory that contains an app folder to store private app components, such as a CRM card. You'll identify this directory by name in the hsproject.json config.
  • An app.json file in the app folder to configure the private app.
Basic folder structure path

Below, learn more about the above files and folders, along with other project components.

hsproject.json

the hsproject.json file contains the information needed for the CLI to upload a project to your account, including its name and local directory. For example:

// example hsproject.json file { "name": "my_project", "srcDir": "src" }

app folder

The app directory contains the app.json config file for your private app along with config files for custom CRM cards. HubSpot can identify the app folder by any name as long as it contains the app.json file and is within the src directory set in hsproject.json. 

  • app.json: defines the private app, including its name, description, scopes, and the extension files needed to run the app.
  • crm-card.json: in this example, this file defines a CRM card extension, including which CRM records can display the card. The app folder can contain multiple extensions.
projects-app-folder-path

app.functions folder

Within the app folder, you'll also need to include an app.functions folder, which contains serverless function files that provide functionality to your app and its extensions. 

  • crm-card.js: contains the code that the serverless function runs.
  • package.json: contains metadata about the serverless function, along with any third party dependencies your project is using.
  • serverless.json: the serverless function config file.
projects-app-functions-folder-path

Builds and deploying

When you're ready to deploy your project from your local environment to a HubSpot account, you'll build your project running the hs upload command. On upload, the build will be triggered and HubSpot will validate your project files and provision any needed resources. By default HubSpot will automatically deploy successful builds.

Alternatively, you can link a GitHub repository to the project to automatically trigger a new build when you push a change to GitHub. This enables you to use GitHub tools and workflows to streamline project development.

To view a deployed project's build history in HubSpot:

  • In your HubSpot account, navigate to CRM Development.
  • In the left sidebar menu, navigate to Projects. 
  • Click the name of the project.
  • On the Builds tab, you can view the project's latest build, deployed build, and its recent build history.

From the project 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. 

project-private-app-settings-tab0

Next, get started building a project by first reviewing the setup guide, then walking through the quickstart guide.

Additional resources

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