UI Extensions quickstart guide (BETA)
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.
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.
npm install -g @hubspot/cli@latestto update the HubSpot CLI to the latest version.
hs initto initialize the HubSpot configuration file to connect the CLI to your HubSpot account.
- 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
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 installto load the dependencies required to start local development server.
- This sample project automatically includes some of the local dependencies specified in the
package.jsonfile. If you're modifying these dependencies in other projects, you may need to run
npm installin both the
- 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).
- To create and test your extension in the production account, select
< ! Test on this production account ! >.
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
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 devagain to restart the server.
With the local development server running, you can view the extension from a contact record in HubSpot (as configured by
objectTypes in the
- 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.
- 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.
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
Linkto the import at the top of the file to make the component available for use.
- Then add the
Linkcomponent beneath the
- 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.
Thank you for your feedback, it means a lot to us.