Quickstart guide for developing with projects (BETA)

  • Sales Hub
    • Enterprise
  • Service Hub
    • Enterprise

Use the guide below to get started with a project template that you can deploy to HubSpot. By the end of this walkthrough, you’ll have built and deployed a private app to your HubSpot account that will add a custom CRM card to the middle pane of your contact records.

Before you get started, make sure you’ve reviewed the setup guide to configure your local environment and set up a development sandbox if needed. 

1. Create a local project

To create your project locally:

  • Navigate to the folder where you set up your local environment during the setup process
    • If you’re using an editor like Visual Studio Code, you can open this folder by navigating to File > Open, then selecting the folder.
    • If you’re using the terminal, you can navigate into the folder using the cd command. For example, if you created the folder within your Documents folder, your command might be cd Documents/myProjects. If you’re not sure where you are in the terminal, you can run pwd to show your current directory.
  • In the terminal, run hs project create

If you encounter an error that reads A hubspot.config.yml file could not be found, ensure that you’re in the folder where you originally ran hs init. If you haven’t run that, view the setup guide before proceeding.

  • Then, follow the terminal prompts to set up your project:
    • Enter a name for your project, then press Enter.
    • Set the location for your project. By default, the location will be set to the current directory. Press Enter.
    • Select whether to start the project from scratch or from the Getting Started template. For this guide, use the arrow keys to select Getting Started, then press Enter.

A project folder will then be created for you, and you can view the project files and folders. For a full overview of project files included in the Getting Started template, view the projects overview.

2. Upload and deploy your project

With your project created, you can now upload it to your HubSpot account. During the upload process, your project will automatically build and deploy, and then be viewable within the account. You can later update your project’s auto-deploy setting to prevent HubSpot from automatically deploying a successful build.

  • In the terminal, ensure you're in the project folder by running cd projectFolderName. Then, run hs project upload.
  • The terminal will display the project’s upload progress, including any errors.

Using this guide, your project should upload successfully. However, in general if you encounter an error during the build or deploy process, you can view a project’s build history in your HubSpot account.

By default, the project will be deployed to your default account. Learn how to change the default account with the hs accounts use command, or how to specify uploading to a specific account with the --account flag. 

3. View your project in HubSpot

View your project in HubSpot to view its build history, version, and settings.

  • In your HubSpot account, navigate to CRM Development.
  • In the left sidebar menu, select Projects. On the Projects page, you can view all your projects, along with their version number and deploy status.
  • Click the name of your project.
  • On the Builds tab, you can view the project's build history. You can also view more information about the app by clicking View in private apps under Deployed Build.projects-view-in-private-apps
  • To view the CRM card in HubSpot:
    • Navigate to a contact record.
    • In the middle pane of the contact record, click the Custom tab.
    • View the Example CRM Card card in the middle pane.
Now that you've successfully deployed the project to HubSpot and reviewed the CRM card, learn more about creating CRM cards with projects, or view other example CRM cards in HubSpot's example extension library on GitHub.

If you want to add another third party dependency to your project, or if you need to upgrade the version of the HubSpot NodeJS client library, check out the guide on managing NPM dependencies in a serverless function.

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