UI extensions for private apps quickstart (BETA)

APPLICABLE PRODUCTS
  • Sales Hub
    • Enterprise
  • Service Hub
    • Enterprise

This quickstart guide walks through setting up HubSpot's example UI extension, which includes a card for contact records. This card sends data from the React front end to the serverless function back end, then displays that data in a success alert. You’ll then customize the card by adding a new component. By the end of this guide, you'll be familiar with the basic processes of developing UI extensions locally with React.

Please note: building UI extensions for private apps in a standard HubSpot account requires a Sales Hub or Service Hub Enterprise subscription. However, you can try out building private apps using projects in developer test accounts for free.

Prerequisites

Before proceeding, ensure that you've opted in to the CRM development tools beta.

This guides assumes that you're already familiar with:

1. Set up your local environment

Because UI extensions are developed locally, you'll first need to set up your environment:

  • Install Node.js which enables HubSpot’s local development tools. Versions 18 or higher are supported. It's recommended to use a package manager like Homebrew or nvm to install Node.
  • Navigate to the directory where you'll be storing your project, app, and extension files.
  • Run npm install -g @hubspot/cli@latest to update the HubSpot CLI to the latest version. 
  • Run hs init, then follow the prompts to initialize the HubSpot configuration file to connect the CLI to your HubSpot account. 

After setting up your environment, proceed to the next steps where you'll create your project.

2. Create a new project

  • Create a new project in your working directory. 
hs project create
  • After running the command, you'll be prompted to name the new project, select its location, then select a template. For this guide, select the CRM getting started project. A new directory will then be created using the project name you assigned.
  • Navigate into the new directory by running cd <project-directory>, then run npm install to load the dependencies required to start local development server.
cd <project-template-directory> npm install

Please note:

  • This sample project automatically includes some of the local dependencies specified in the package.json file. If you're modifying these dependencies in other projects, you may need to run npm install in both the src/app/extensions and src/app/app.functions directories.
  • This sample project uses a free API which doesn't require any secret handling. Learn more about how to include secrets so that they're accessible during local development and when deployed.

3. Start local development

To start local development, you'll use the hs project dev command. This command will walk you through setting up a development sandbox and allow you to test changes locally before uploading to your development sandbox or production account.

hs project dev
  • After running hs project dev, select the account you want to work in:
    • To create your extension in an existing sandbox, use the arrow keys to select the sandbox, then press Enter.
    • To create and test your extension in a new development sandbox, select < Test on a new development sandbox >. Then, name the sandbox and press Enter. HubSpot will then create the new development sandbox in the production account. This sandbox will sync with the production account's data, including CRM object definitions and up to 100 of the most recently created contacts and their associated deals, tickets, and companies (up to 100 each).
Please note: if you receive the error The personal access key you provided doesn't include sandbox permissions, you'll need to deactivate the account's Personal Access Key, then create a new one with sandbox permissions. To do so, run hs auth, then follow the prompts to select your account. Then, click Deactivate next to the personal access key, and generate a new one with the proper scopes.
  • To create and test your extension in the production account, select < ! Test on this production account ! >.
If a project has multiple extensions, you'll be prompted to select which extension to run. You can run multiple extensions from the same app, but not multiple extensions across multiple apps.

Once the project is created, built, and deployed in the selected account, the local development server will start and you can begin building and modifying your extension. 

  • The browser will automatically refresh to pick up the latest saved front end code. This includes changes made to React files and serverless functions. Note that changes to serverless functions will be picked up at invocation time.
  • Changes made to configuration files, such as app.json and hsproject.json, require a manual upload before you can continue development. To upload those changes, first stop the local development server with q, then run hs project upload. After your changes are uploaded, run hs project dev again to restart the server.

4. View the extension in HubSpot

With the local development server running, you can add the card to the contact record view, then view the card:

  • Log in to your HubSpot account.
  • In your HubSpot account, navigate to Contacts > Contacts. Then, click the name of a contact to view its record.
  • At the top of the contact record, click Customize tabs. A new tab will open showing the record editor sidebar.
    crm-recrd-customize-tabs
  • In the right sidebar, click Default view to edit the default contact record view.
  • For the purposes of this tutorial, click the + plus icon tab at the top of the editor to add a new tab.
    crm-record-page-editor-add-tab
  • In the dialog box, enter a name for your new tab, then click Done.
  • With the new tab added, click the Add cards dropdown menu, then select your new card.
  • In the top right, click Save and exit.
  • Navigate back to the contact record, then refresh the page. You should now see your new tab, which will contain your new card. With the local development server running, you'll see a Developing locally tag displayed at the top of the card.

ui-ext-card-quickstart-resultLearn more about customizing record views on HubSpot's Knowledge Base.

5. Add a new component to the card

With the card uploaded and local development server running, you'll now add a new UI component to the card and refresh the page to see your changes.

Because the React file serves as the extension's front end, you'll find the UI extension components in the Example.jsx file in the app/extensions directory. For the purposes of this guide, you'll add a Link component to link out to the UI extension components reference document.

  • First, add Link to the import at the top of the file to make the component available for use.
import { Tile, Button, Text, Input, Stack, hubspot, Link } from '@hubspot/ui-extensions';
  • Then add the Link component beneath the Button component.
return ( <> <Text> <Text format={{ fontWeight: 'bold' }}> Your first UI Extension is ready! </Text> Congratulations {context.user.firstName}! You just deployed your first HubSpot UI extension. This example demonstrates how you would send parameters from your React frontned to the serverless function and get response back. </Text> <Input name="text" label="Send to serverless" onInput={(t) => setText(t)} /> <Button type="submit" onClick={run}> Click me </Button> <Link href="https://developers.hubspot.com/docs/platform/ui-extension-components"> See all UI extension components </Link> </> );
  • Save your local changes. This will trigger the local development server to update and reload the extension.
  • The CRM record page should now show the new component without requiring a refresh.
ui-ext-card-quickstart-step-5

Next steps

Now that you're familiar with the basics of creating, uploading, and updating a UI extension, you can continue customizing the example card with other UI components, updating the serverless function to fetch different data, or create a new card from scratch. 

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