HubSpot projects overview (BETA)
Sales Hub
- Enterprise
Service Hub
- Enterprise
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.
Private apps enable you to send/retrieve data for your UI extensions, 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.
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 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.
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 thehsproject.json
config. - An
app.json
file 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
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:
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 directory set by srcDir
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.
Learn more about private app configuration.

Serverless function folder
Within the app folder, you'll also need to include a serverless function folder, which contains serverless function files that provide functionality to your app and its extensions. HubSpot will recognize any folder that contains a serverless.json
file as a serverless function folder.
crm-card.js
: contains the code that the serverless function runs. Learn more about this file in the serverless functions guide.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.
Next, get started building a project by first reviewing the setup guide, then walking through the quickstart guide.
Thank you for your feedback, it means a lot to us.