HubStarter Pro Documentation

Getting Started

Welcome to HubStarter Pro! This toolkit helps you build powerful HubSpot UI Extensions quickly and efficiently. HubStarter Pro provides pre-made templates, components, and utilities to accelerate your development workflow for HubSpot's UI Extensions (currently in beta). Before using HubStarter Pro, ensure you've set up the HubSpot development environment by following the official [HubSpot Developer Projects documentation](https://developers.hubspot.com/docs/guides/crm/developer-projects/create-a-project).

Prerequisites

Before using HubStarter Pro, ensure you have:

• Completed the HubSpot developer environment setup
• Access to the HubSpot UI Extensions beta program
• Basic knowledge of React and HubSpot's CRM
• Authenticated your local environment with HubSpot

Installation

After setting up your HubSpot development environment according to the [official documentation](https://developers.hubspot.com/docs/guides/cms/quickstart/react-plus-hubl-quickstart), install HubStarter Pro:

npm install hubstarter-pro
# OR
yarn add hubstarter-pro

HubSpot Authentication

Before developing, you need to authenticate with HubSpot:

hs auth

Follow the prompts to complete the authentication process. You'll need to create a personal access key in your HubSpot developer account.

Creating a UI Extension Project

Use HubStarter Pro to scaffold a new UI Extension project:

npx hubstarter-pro create my-extension
cd my-extension

This creates a new project with the required structure for HubSpot UI Extensions, including configuration files and React components.

Project Structure

Your HubStarter Pro UI Extension project follows the HubSpot Developer Project structure:

my-extension/
├── .hubl/
├── src/
│   ├── app/
│   │   ├── extensions/
│   │   │   ├── my-extension/
│   │   │   │   ├── app.json
│   │   │   │   ├── components/
│   │   │   │   └── index.jsx
│   │   ├── crm/
│   └── index.js
├── hsproject.json
└── package.json

Each extension is contained within its own directory with an app.json configuration file.

Available Templates

HubStarter Pro includes several pre-built templates for UI Extensions:

• crm-card - Custom card for contact, company, deal records
• custom-tab - Add a custom tab to record pages
• data-fetch - UI Extension with API data integration
• form-extension - Custom form field or validator

Local Development

Start the development server and watch for changes:

npm start
# OR
yarn start

This runs a local development server that connects to your HubSpot account for testing your UI Extensions.

Using Components

HubStarter Pro provides components compatible with HubSpot's UI Extensions:

import { Card, Button, TextField } from '@hubstarter/components'
import { useHubSpotCrmData } from '@hubstarter/hooks'

export const MyExtension = () => {
  const { data, loading } = useHubSpotCrmData('contacts');
  
  return (
    <Card title="My Custom Extension">
      {loading ? (
        <p>Loading...</p>
      ) : (
        <TextField 
          name="email"
          label="Email Address" 
          initialValue={data.properties.email}
        />
      )}
      <Button variant="primary">Save</Button>
    </Card>
  );
}

Our components follow HubSpot's UI design patterns and integrate with their data model.

Deploying UI Extensions

When you're ready to deploy your UI Extension:

npm run deploy
# OR
yarn deploy

This builds your extension and uploads it to your HubSpot account as a Developer Project. You can then enable the extension in your HubSpot portal.

Extension Configuration

Configure your UI Extension in the app.json file:

{
  "name": "My Custom Extension",
  "description": "A custom UI extension for contact records",
  "uid": "my_custom_extension",
  "scopes": ["crm.objects.contacts.read"],
  "public": false,
  "extensions": {
    "crm": {
      "cards": [
        {
          "file": "index.jsx",
          "location": "crm.record.tab",
          "associatedObjectTypes": ["CONTACT"]
        }
      ]
    }
  }
}

The configuration specifies where your extension will appear in the HubSpot interface and what permissions it requires.

Troubleshooting

Common issues and their solutions:

API Reference

HubStarter Pro provides the following modules for UI Extensions:

• @hubstarter/components - UI components matching HubSpot's design system
• @hubstarter/hooks - React hooks for HubSpot CRM data access
• @hubstarter/utils - Utility functions for common UI Extension operations
• @hubstarter/templates - Full extension templates for common use cases

FAQ