[HubSpot] [Developer Platform] Adding Custom Cards to Record Screens

A "New Developer Platform"...?

I heard that HubSpot's "private apps" were being treated as legacy, and I hadn't been able to keep up with it at all... 😑
I've finally read through the documentation, so I'd like to summarize this so-called "new developer platform" 📝

It seems that the Japanese version of the HubSpot Developers documentation is slow to update, so I recommend referring to the English version 𓏼˙₊🕊️◝ྀ
(Has the translation always had such a lag? I guess it is what it is...)

What is the Developer platform?

It seems that HubSpot's new Developer platform is an integrated place for developing apps and CRM.

HubSpot’s new developer platform, version 2025.2, provides multiple advantages over legacy private and public apps, including a new file-based build-and-deploy framework. This framework contains an app’s configuration, assets, and other source code. Developer platform

Until now, there were:

• Private apps for internal use
• Public apps to be listed on the App Marketplace
• Projects for theme development, serverless functions, etc.

Everything was quite scattered, so maybe the idea is to group them all together and manage them as "projects"? 🪄︎︎🫧
💭

៸៸ ۪🎧ׂ There was also this video, so I'll leave the link here
https://www.youtube.com/watch?v=OA7GaHh5hb8

Let's open the [Develop] screen

You can open the Developer overview page from the HubSpot menu > [Develop].

📄∘˙ To access the [Develop] screen, you need the following permissions/seats (I didn't know they created a "developer seat"...💭)

Super admins, partner admins, and users with either a developer seat or the Developer tools access permission can access the developer overview page. Developer overview

When you open the Developer overview page, there is a [Projects] menu.

It seems this "Project" will be the unit for future development 🐬ྀིྀི‹₊˚ Since I have things I created in the past in my environment, several are displayed.

*Traditional private apps have been pushed to [Legacy apps]... 🤧ˎˊ˗

Regarding previously created projects

I had never really paid attention to this, but apparently, projects have versions.
The ones I created in the past were version 2023.1 or 2023.2, and since version 2025.2 has been released with the advent of this Developer platform, it seems they need to be updated to this version.

📄∘˙ You cannot build unless you update to the latest version

There hadn't been an update since 2023.2, so there's no way I would have noticed...

https://developers.hubspot.com/docs/developer-tooling/platform/versioning

I'll update them if I feel like it, but today I'll just create a new project 𓈒⁺🕊️⸝⸝

Let's build App cards

Now, let's try building something using the Developer platform 🪄༘✩

About App cards

This time, I'll try custom-developing a "card" that can be displayed on contact or company record screens.

I feel like this record screen card development used to be called UI extensions,
but now it seems to be called "App cards".

https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/app-cards/overview

As for App cards, there was the tutorial below, so I will try it based on this 𓈒⁺🕊️⸝⸝
https://developers.hubspot.com/docs/getting-started/quickstart

1. Set up the HubSpot CLI

Install the HubSpot CLI, which is the local development environment for HubSpot, into your working directory.

Since I've summarized how to use it with VS Code below, I recommend VS Code users to proceed this way ꕀ🐶ˊ˗
https://zenn.dev/raynya/articles/hubspot-vscode-cli

You need to have version 7.6.0 or higher installed to proceed with this tutorial.

However, as mentioned below, it is recommended to install the latest 7.11.2 if possible:

The latest version of the HubSpot CLI, which is recommended, is 7.11.2. You can check which version of the CLI you have installed by running hs --version. Install the HubSpot CLI

If you already have the HubSpot CLI installed, try checking if the version is 7.6.0 or higher with:

hs --version

To update to the latest version, use this command 🐈‍⬛⸝⋆

npm i -g @hubspot/cli@latest

2. Create and upload a project

1. Once the HubSpot CLI installation is complete, proceed with creating a sample project using the hs get-started command.

hs get-started

You can also create a project with hs project create.

When you use hs get-started,
it says:

We'll create a new project with a sample app for you.Projects are what you can use to create apps with HubSpot.Usually you'll use the hs project create command, but we'll go ahead and make one now.

So it seems good to differentiate them like this:

• If the usage is already decided, use hs project create
• If you just want to deploy something for now, use hs get-started
  🐰 ∘°

1. It will ask Are you looking to build apps or CMS assets?, so select App.
2. It will ask Enter your project name, so enter the project name (any value; I'll safely use app_cards-quicksart).
3. It will ask Choose where to create the project, so specify the directory where you want to place the project (if you have the working directory open, just pressing Enter is OK).

4. It will ask ? Would you like to upload this project to account <portal name>, so press Y to upload it.
5. The HubSpot CLI will work hard to build and deploy 🚀 ⌢ ۪۫, so watch it.

When [SUCCESS] Project uploaded successfully! is displayed, the upload is successful! ˗ˏˋ₊ʚ🌟ɞ₊ˎˊ˗

3. Install the app and verify!

1. Confirm that the project created this time exists under HubSpot [Develop] > [Projects].

2. When you open the project you created, you can see that an app called "My Get Started app" has been created.

📄∘˙ I think this corresponds to what used to be a private app, but in the Developer platform, it seems to be called a "project component".

3. Open Project > Apps, and install the app from the [Distribution] tab > [Install now].
   

📄∘˙ A screen like this will appear, but since it's an app I'm making, I'll proceed with [Connect app].

If "My Get Started app" appears in the list of [Connected apps], the installation is complete! ˗ˏˋ₊ʚ🌟ɞ₊ˎˊ˗

4. Let's add a card to the contact record

1. Once the app installation is complete, enter the hs project dev command to start the local development server.

hs project dev

At this time, let's run the command after moving to the project directory 🐰 ∘°
Also, although it might not be recommended, I am running it directly on the production environment this time.

2. When the local development server starts, a screen like this 👇 will appear in your browser, indicating that it is in a Connected state.

3. Clicking [Setup preview] will redirect you to the configuration screen? [App cards] tab of the "My Get Started app" app under [Connected apps]. Let's set it up here so that the card is displayed on the record page.
   

My environment only has the default view, so it looks like the above, but if you have created a view in [Settings] > [Contacts] > [Customize records], you should be able to select any view 🐰 ∘°

4. Opening the view configuration screen shows that the added "Get Started App Card" has been added.
   *I adjusted the position for easier viewing. If you add it in step 3, the card is added at the very bottom.
   

5. Open a contact record again, and you can see the added card displayed ⊹˙∘•💫ᯓ (Yay!)

📄∘˙ The yellow "Developing locally" tag seems to be there to let you know that the local development server is running.

You’ll then be redirected back to the contact record, and the app card will display with a Developing locally tag to indicate that the local development server is waiting to detect local changes. Setup local development preview

5. Let's customize the card a little

Since I've come this far, let's customize the created card a little ‧₊ 🍥 ˚✩

App cards projects are created with the following structure:

myProject
└── src/
    └── app/
        └── cards/
            ├── NewCard-hsmeta.json
            ├── NewCard.jsx
            └── package.json

Among these, the jsx file is the part that constitutes the card's appearance 🪞⟡, so let's tweak the file corresponding to this.

1. Find app_cards-quickstart\src\app\cards\get-started-app-card.tsx from the directory where the project was created.
2. get-started-app-card.tsx had the following structure, so this time I'll try adding some text.

import React from "react";
import { Text, Link, List, EmptyState } from "@hubspot/ui-extensions";
import { hubspot } from "@hubspot/ui-extensions";

hubspot.extend<'crm.record.tab'>(() => <Extension />);

const Extension = () => {

  const appCardDocsLink = 'https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/app-cards/overview';

// The content below return is what will be displayed on the card
  return (
    <>
      <EmptyState
        title="Build your app card here!"
        layout="vertical"
        imageName='building'
      >
+       <Text>
+       I tried making an App Card🐈！
+       </Text>
        <Text>
          Add a layer of UI customization to your app by including app cards that can display data, allow users to perform actions, and more.
          Visit the <Link href={appCardDocsLink}>app card documentation</Link> for more info, or check out the following links to get inspired:
        </Text>
        <List variant="unordered-styled">
          <Link href="https://developers.hubspot.com/docs/platform/ui-components">
            📖 Explore our library of UI components
          </Link>
          <Link href="https://ecosystem.hubspot.com/marketplace/apps/app-cards">
            📖 Look at the Marketplace collection of apps that contain app cards
          </Link>
          <Link href="https://developers.hubspot.com/slack">
            ▶️ Connect with developers on #ui-extensions channel on developer
            Slack community
          </Link>
        </List>
      </EmptyState>
    </>
  );
};

3. Save the edited file > Reload the contact record screen, and you can see the added text displayed on the card ⊹˙∘•💫ᯓ (Yay yay!)

📄∘˙ Because the local development server is running, changes are automatically reflected as a preview.

The state above is a state where the locally edited content is being previewed.
Therefore, don't forget to execute hs project upload in the next step to reflect the changes in the production environment 𓂃 ໋ 🚀

4. To reflect the changed additions in the production environment, execute hs project upload.

hs project upload

At this time, let's stop the local development server with q 🐰 ∘°

5. Once build -> deploy -> upload are complete, reload the contact record screen you were checking earlier to confirm that the changes have been reflected.

📄∘˙ The "Developing locally" tag that was there earlier is gone, and you can see that the added text is displayed.
👉 I was able to successfully reflect it in the production environment ⊹˙∘•💫ᯓ (Yay yay yay!)

Conclusion (monologue)

I had touched custom cards a tiny bit during the UI extensions era, but my impression was that the fine details had changed due to the Developer platform ⋆ 𖦆 💭

I have mixed feelings about private apps not being easy to create ˚｡ ꒷💭, but managing primarily by "projects" is consolidated and easy to understand, and if you don't have resistance to the CLI, I think it might be easy to use.

There are still updates I haven't caught up with, so I'll summarize them when I do ゛﹒๑🐑