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:
- Install Node.js which enables HubSpot’s local development tools. Versions 10 or higher are supported.
- Navigate to the directory where you'll be storing your project, app, and extension files.
npm install -g @hubspot/cli@latestto update the HubSpot CLI to the latest version.
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
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 add the card to the contact record view, then view the custom 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 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.