HubSpot projects overview (BETA)
In this guide, learn more about the anatomy of a project and how to manage it in HubSpot once deployed.
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 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.
Learn more about creating serverless functions with projects.
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:
hsproject.jsonfile in the root directory to configure the project.
srcdirectory that contains an app folder to store private app components, such as a CRM card. You'll identify this directory by name in the
app.jsonfile in the app folder to configure the private app.
Below, learn more about the above files and folders, along with other project components.
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:
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
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.
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.
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.
Thank you for your feedback, it means a lot to us.