The features described in this guide are in Early Access beta, separate from the CRM development tools to build UI extensions with React as frontend beta for private app UI extension development. 

Request access to the UI extensions for public apps beta

Build UI extensions for public apps (BETA)

To customize the HubSpot UI, from CRM record views to the help desk preview panels, you can build UI extensions. UI extensions are built locally using the developer projects framework, and are powered by a public or private app, depending on your needs. The toolset for developing UI extensions is largely the same whether you're building for a public or private app, with a few differences in authentication, installation, and feature support.

Below, learn about building UI extensions for public apps at a high level. For more detail, follow the links in each section.

ui-extension-sample-multi-step-flow-with-panel

UI extensions in public apps vs private apps

UI extensions can be built for both private apps and public apps, and follow the same principles and limitations in both types of apps. However, while most UI extension concepts are transferable from private apps to public apps, there are two key differences:

  • When developing a UI extension using a private app, you install the app directly in the target production account. When developing using a public app, you instead build the app in a developer account, then its install URL can be used to install it into other accounts. So while private apps are created on a per-account basis, public apps are intended to be installed across multiple accounts.
  • UI extensions in private apps use serverless functions and the private app's access token to fetch external data. UI extensions in public apps instead require you to bring your own self-hosted back end and use the hubspot.fetch() API.

public-apps-vs-private-apps

Creating and configuring public apps

Using the CLI, you can create a project with a public app using any of the following methods:

Whichever method you choose, you'll handle app configuration in the app’s public-app.json file Learn more about creating and configuring apps.

UI extension development

When building UI extensions, check out the following resources to learn more about the utilities, functionalities, and components available to you:

Local development

While developing UI extensions, you can run a local development server to see your saved changes in real-time without needing to re-upload the project. The local development server is only available for the front end portion of the app, and assumes the backend is either running locally or is hosted. Because public apps require you to bring your own back end, there are a few differences for running local development for public apps, depending on your setup.

Learn more about local development.

Fetching data

While private apps can use serverless functions to fetch data, when you build UI extensions inside public apps, you need to bring your own REST-based backend and use the hubspot.fetch() API to fetch data. You'll specify the URLs that the app can request data from in the allowedUrls array in the public-app.json file. 

Learn more about fetching data with hubspot.fetch.

Working with webhooks

Build webhooks into your app to subscribe to events happening in the account that the app is installed in. Webhooks in project-based public apps can use generic webhook subscriptions to subscribe to events for a wide range of HubSpot objects. However, you can still subscribe to classic webhook subscriptions by including a legacyCrmObjects or HubEvents, depending on the subscription type.

Webhook subscriptions are defined in the webhooks.json file within a webhooks folder in the same directory as your app (e.g., src/app). You'll also need to update your public-app.json configuration file to reference that file.

Learn more about using webhooks in public apps.

App Marketplace guidelines

All apps built for the App Marketplace are subject to the App Marketplace listing requirements, and certified apps are subject to the additional App Marketplace certification requirements. If you're adding a UI extension to an app intended for the App Marketplace, you'll need to adhere to the additional criteria below.

Compliance

  • Naming: per the App Partner Program branding guidelines:
    • Do not modify, imitate, or abbreviate any HubSpot brands or names (e.g., "HubSpot," "Hub," etc.) anywhere in the name of your UI extension.
    • Do not use a generic product name + any HubSpot brands or names (e.g., "UI extension for HubSpot").
    • Do not brand your UI extension using the word "inbound" in a way that would tie it to HubSpot's INBOUND event (e.g., "Inbound Sales UI extension").
  • Logos and icons: 
  • Sensitive data:
    • Your app must not be participating in the current sensitive data for public apps private beta.
    • Your UI extension must not display sensitive information, as defined in HubSpot's Terms of Service.

Security and privacy

  • Your app must have advanced scope settings turned on ("advancedScopeSettingsEnabled": true in public-app.json). All required, conditionally required, and optional scopes should be selected to prevent errors. 
  • Your app must use all of the scopes that it requests during installation. Scopes that are not used must be removed. If certain scopes only apply to a subset of your app's user base, they should be included as conditionally required or optional scopes.

Reliability and performance

For linked assets such as images and JavaScript, avoid using absolute links. Instead, use relative links and include the assets in your files. Exceptions may only be made if you use a reputable CDN.

Usability and accessibility

  • Buttons:
    • Forms must include submit Buttons
    • Ensure destructive button styles denote a destructive behavior.
    • Include only one primary button per surface (app card, modal, or panel).
  • Text: 
    • It's recommended to not use underline formatting for text that's next to a hyperlink, as it will also appear clickable.
    • Do not use Tags in place of Buttons or Links.

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