UI Extensions quickstart guide (BETA)

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

This quickstart guide walks through the basic UI extension CRM card sample project, which includes a minimal custom card that 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.

Prerequisites

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:

  • Navigate to the directory where you'll be creating the project that contains your app and UI extension. The project will be created in a new subdirectory.
  • Run npm install -g @hubspot/cli@latest to update the HubSpot CLI to the latest version. 
  • Run hs init to initialize the HubSpot configuration file to connect the CLI to your HubSpot account.

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 Use basic CRM extension card sample project (files only) template. 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).
    • To create and test your extension in the production account, select < ! Test on this production account ! >.
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.

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 view the extension from a contact record in HubSpot (as configured by objectTypes in the example-card.json file):

  • 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.
  • Click the Custom tab at the top of the contact record.

custom-tab-crm-record

  • On the Custom tab, view the UI extension custom card. You'll see a Developing locally tag displayed at the top of the example card.

ui-ext-card-quickstart-result

Please note: if you're enrolled in the record page editor beta, you'll need to click Customize this tab at the top of the CRM record and configure your card to appear on the record page. 

5. Add a new component to the card

With the card uploaded and local development server running, you'll now add a new 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 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.