UI extensions for private apps quickstart (BETA)
-
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.
Before proceeding, ensure that you've opted in to the CRM development tools beta.
This guides assumes that you're already familiar with:
- The basics of React and JavaScript (or optionally Typescript)
- Using the HubSpot CLI for local development
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.
- Create a new project in your working directory.
- 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 runnpm install
to load the dependencies required to start local development server.
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 runnpm install
in both thesrc/app/extensions
andsrc/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.
- 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).
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 ! >
.
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
andhsproject.json
, require a manual upload before you can continue development. To upload those changes, first stop the local development server withq
, then runhs project upload
. After your changes are uploaded, runhs project dev
again to restart the server.
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.
- 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.
- 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.
Learn more about customizing record views on HubSpot's Knowledge Base.
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.
- Then add the
Link
component beneath theButton
component.
- 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.
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.
Thank you for your feedback, it means a lot to us.