Quickstart guide for developing with projects (BETA)

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. You can also view the projects overview guide for more information about project file structure, the build and deploy process, and how to manage projects in HubSpot once deployed.

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.
    project-start-getting-started0

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.
    projects-left-sidebar
  • 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.
      quickstart-crm-card-middle-pane
Below, learn more about where the card's components and details are set within your local files:
  • The card title corresponds with the title field in crm-card.js.
  • The card description corresponds with the text component defined by the introMessage const in crm-card.js.
  • The contact's name is retrieved from the contact's firstname property. This property is referenced in two files:
    • In crm-card.json, the property is first sent to the serverless function through the propertiesToSend array.
    • In crm-card.js, the serverless function references the property (${firstname}) in the first text component within the quoteSections const.
  • The quote and author are displayed by the ${data[0].q} and ${data[0].a} variables in the second and third text components within the quoteSections const in crm-card.js.
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.
Please note: if you've previously customized the overview section, the CRM card will not appear automatically. Instead, you'll need to customize the  after upload to add the card manually. This also applies if you've customized the right sidebar and upload a new CRM card that's set to appear in the sidebar.

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.

Additional resources


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