hubspot-app-builder

HubSpot App Builder（Platform 2026.03）

このスキルでは、最新の開発者プラットフォーム（バージョン 2026.03）での HubSpot アプリの開発について、プロジェクトの作成、設定、UI 拡張機能、サーバーレス関数、エージェントツール、Webhook、配布までを説明します。

Platform version 2026.03 は、2026 年 3 月 30 日にリリースされました（2026 年 4 月 14 日の Spring 2026 Spotlight で GA が確認されました）。アプリでの完全なサーバーレス関数サポート（静的認証アプリを含む）が再導入され、Breeze Agents 向けのエージェントツールが導入され、App Homes が複数ページの App Pages に拡張され、npm ワークスペースによるコード共有が追加されました。以前のバージョン 2025.2 は現在「Supported」ステータスです。

前提条件

• HubSpot CLI v8.3.0 以降：npm install -g @hubspot/cli@latest
• 認証：hs account auth
• Node.js 22 以降（2025.2 で最低バージョンが v22 に引き上げられ、2026.03 でも継続されています。2025.1 では v20 でした）
• HubSpot 開発者アカウント
• 本番環境のサーバーレス関数には Enterprise サブスクリプションが必要です（開発者テストアカウントでは不要です）

プロジェクトのセットアップワークフロー

1. プロジェクトを作成する

hs project create

CLI のプロンプトに従って設定します。

• 配布：marketplace（App Marketplace に掲載する場合）または private（特定のアカウント向け）
• 認証：oauth（複数アカウント）または static（単一アカウント）
• 機能：card、settings、pages、app-function、serverless-function、webhooks、workflow-action から選択します

後から機能を追加するには：

hs project add

2. プロジェクトのファイル構成

my-project-folder/
├── hsproject.json                    # Must include "platformVersion": "2026.03"
├── packages/                         # Shared code (npm workspaces, optional)
│   └── shared-utils/
│       ├── index.ts
│       └── package.json
└── src/
    └── app/
        ├── app-hsmeta.json          # Top-level app config (required)
        ├── cards/                    # UI extension cards
        │   ├── MyCard.jsx
        │   ├── my-card-hsmeta.json
        │   └── package.json
        ├── pages/                    # App Pages (multi-page, formerly App Homes)
        │   ├── HomePage.jsx
        │   ├── home-page-hsmeta.json
        │   ├── DetailPage.jsx
        │   ├── detail-page-hsmeta.json
        │   └── package.json
        ├── settings/                 # App settings page
        │   ├── Settings.tsx
        │   ├── settings-hsmeta.json
        │   └── package.json
        ├── functions/                # Serverless functions (2026.03 format)
        │   ├── myFunction.js
        │   ├── myFunction-hsmeta.json   # Individual config per function
        │   └── package.json
        ├── app-events/               # App events (open beta)
        │   └── my-event-hsmeta.json
        ├── app-objects/              # App objects (open beta)
        │   └── my-object-hsmeta.json
        ├── webhooks/                 # Webhook subscriptions
        │   └── webhooks-hsmeta.json
        └── workflow-actions/         # Custom workflow actions / Agent tools
            └── custom-action-hsmeta.json

3. app-hsmeta.json を設定する

{
  "uid": "my_app_uid",
  "type": "app",
  "config": {
    "name": "My App",
    "description": "App description for installing users.",
    "distribution": "marketplace",
    "auth": {
      "type": "oauth",
      "redirectUrls": ["http://localhost:3000/oauth-callback"],
      "requiredScopes": ["crm.objects.contacts.read"],
      "optionalScopes": [],
      "conditionallyRequiredScopes": []
    },
    "permittedUrls": {
      "fetch": ["https://api.example.com"],
      "iframe": [],
      "img": []
    },
    "support": {
      "supportEmail": "[email protected]",
      "documentationUrl": "https://example.com/docs"
    }
  }
}

主なルール：

• uid はプロジェクト内で一意である必要があります（最大 64 文字、英数字と _、-、. を使用）
• type は親フォルダー名（app）と一致する必要があります
• 単一アカウント向けのプライベートアプリでは、static 認証を使用し、redirectUrls を削除します
• 少なくとも 1 つの read スコープを含めます（例：crm.objects.contacts.read）

4. アップロードしてデプロイする

hs project upload          # Upload and trigger a build
hs project open            # Open project in HubSpot browser
hs project dev             # Start local dev server with hot reload
hs project install-deps    # Install package.json dependencies

5. アプリをインストールする

アップロード後、HubSpot UI からインストールします。

• Development > Projects > [Project Name] > [App UID] に移動します
• Distribution タブをクリックします
• テストアカウントの場合：Add test install(s) をクリックします
• 通常のアカウントの場合：Install now をクリックします

UI 拡張機能

すべての UI 拡張機能は、*-hsmeta.json 設定ファイルと React コンポーネントファイル（.jsx または .tsx）で構成されます。

アプリカードの設定（cards/*-hsmeta.json）

{
  "uid": "my-card",
  "type": "card",
  "config": {
    "name": "My Card",
    "description": "Card description.",
    "location": "crm.record.tab",
    "entrypoint": "/app/cards/MyCard.jsx",
    "objectTypes": ["contacts"]
  }
}

サポートされている配置場所：

配置場所	値	備考
CRM の中央列	crm.record.tab	最も一般的です。カスタムタブをサポートします
CRM の右サイドバー	crm.record.sidebar	ここでは CRM データコンポーネントを使用できません
CRM のプレビューパネル	crm.preview	CRM 全体のレコードプレビュー
ヘルプデスクのサイドバー	helpdesk.sidebar	tickets スコープが必要です
App Pages（旧 App Home）	home	複数ページの全画面エクスペリエンスです。ナビゲーションには PageRoutes と PageLink を使用します
アプリ設定ページ	settings	HubSpot 設定内の設定 UI

サポートされている objectTypes： contacts、companies、deals、tickets、orders、carts、p_customObjectName、app_object_uid

React コンポーネントのパターン

import React from "react";
import { hubspot, Text, Button, Flex } from "@hubspot/ui-extensions";

// Required: register extension with HubSpot
hubspot.extend(({ context, actions }) => (
  <MyCard context={context} addAlert={actions.addAlert} />
));

const MyCard = ({ context, addAlert }) => {
  return (
    <Flex direction="column" gap="medium">
      <Text>Hello, {context.user.firstName}!</Text>
      <Button onClick={() => addAlert({ type: "success", title: "Done", message: "Action completed" })}>
        Click me
      </Button>
    </Flex>
  );
};

SDK フック（推奨される方法）

import { hubspot, Button, useExtensionApi } from "@hubspot/ui-extensions";
import { useCrmProperties } from "@hubspot/ui-extensions/crm";

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

const MyCard = () => {
  // Access both context and actions
  const { context, actions } = useExtensionApi<'crm.record.tab'>();

  // Fetch CRM properties from the current record
  const { properties, isLoading } = useCrmProperties(["firstname", "lastname", "email"]);

  if (isLoading) return <Text>Loading...</Text>;

  return (
    <Button onClick={() => actions.addAlert({ message: `Hello ${properties.firstname}!` })}>
      Say Hello
    </Button>
  );
};

利用可能なフック：

• useExtensionApi<location>() — コンテキストとアクションの両方にアクセスします
• useExtensionContext<location>() — コンテキストのみにアクセスします
• useExtensionActions<location>() — アクションのみにアクセスします
• useCrmProperties(["prop1", "prop2"]) — @hubspot/ui-extensions/crm から利用します
• useAssociations({ toObjectType, properties, pageLength }) — @hubspot/ui-extensions/crm から利用します

外部データの取得

import { hubspot } from "@hubspot/ui-extensions";

// GET
const response = await hubspot.fetch("https://api.example.com/data", {
  method: "GET",
  timeout: 5000,
});
const data = await response.json();

// POST — body is a plain object, not JSON.stringify()
const response = await hubspot.fetch("https://api.example.com/data", {
  method: "POST",
  body: { key: "value" },
});

ネイティブの fetch との主な違い：

• body はプレーンオブジェクトです。JSON.stringify() を使用したり、Content-Type を手動で設定したりしないでください
• カスタムヘッダーとしてサポートされるのは Authorization のみです
• URL は permittedUrls.fetch に記載する必要があります。localhost は許可されません（プロキシを使用してください）
• HubSpot はすべてのリクエストに userId、portalId、userEmail、appId をクエリパラメーターとして追加します
• 同時リクエストは最大 20 件、タイムアウトは 15 秒、ペイロードの上限は 1MB です

バックエンドでは、受信するすべてのリクエストで X-HubSpot-Signature-v3 を検証する必要があります。詳しくは references/signature-validation.md を参照してください。

詳しいガイド（プロキシの設定、Authorization ヘッダーのパターン、ローカル開発時の署名、モニタリング）については、references/fetching-data.md を参照してください。

サーバーレス関数（2026.03 形式）

プラットフォームバージョン 2026.03 では、静的認証を使用するアプリを含め、アプリ向けのサーバーレス関数の完全なサポートが再導入されました。サーバーレス関数は HubSpot のインフラストラクチャ内でサーバー側の JavaScript を実行するため、外部サーバーは不要です。

重要： 2026.03 では、2025.1 で使用されていた単一の serverless.json に代わり、関数ごとの新しい -hsmeta.json 設定ファイルを使用します。各関数には、src/app/functions/ 内に独自の設定ファイルがあります。

サーバーレス関数の種類

• プライベート（アプリ）関数 — App Cards、App Pages、App Settings から UI 拡張機能が呼び出す内部関数です。Enterprise サブスクリプションまたは無料の開発者テストアカウントが必要です。
• パブリックエンドポイント関数 — HTTP でアクセス可能なエンドポイントです。Content Hub Enterprise が必要です。開発者テストアカウントでは利用できません。

ディレクトリ構造（2026.03）

src/app/functions/
├── myFunction.js
├── myFunction-hsmeta.json    # Individual config per function
└── package.json

これは、ネストされた .functions フォルダーと単一の serverless.json を使用していた 2025.1 の構造に代わるものです。

設定（myFunction-hsmeta.json）

プライベートアプリ関数（パブリックエンドポイントなし）：

{
  "uid": "myFunction",
  "type": "app-function",
  "config": {
    "entrypoint": "/app/functions/myFunction.js",
    "secretKeys": ["my_api_key"]
  }
}

パブリックエンドポイントを持つアプリ関数：

{
  "uid": "myPublicFunction",
  "type": "app-function",
  "config": {
    "entrypoint": "/app/functions/myPublicFunction.js",
    "secretKeys": ["my_api_key"],
    "endpoint": {
      "path": "my-endpoint",
      "method": ["GET", "POST"]
    }
  }
}

サーバーレス関数のパターン

// myFunction.js
const hubspot = require("@hubspot/api-client");

exports.main = async (context = {}) => {
  const hubspotClient = new hubspot.Client({
    accessToken: process.env.PRIVATE_APP_ACCESS_TOKEN,
  });

  try {
    const res = await hubspotClient.crm.contacts.basicApi.getPage();
    return res;
  } catch (err) {
    console.error(err);
    return err;
  }
};

主な注意事項

• アクセストークンには context.secrets ではなく process.env を使用します
• Async/await が必須です（コールバックはサポートされなくなりました）
• ログサイズは最大 256KB で、実行順序が保証されます
• シークレットは hs secret add CLI コマンドで管理します
• NPM パッケージがサポートされています
• 本番環境では Enterprise サブスクリプションが必要です（テストアカウントでは不要です）
• 本番環境に移行する前に安全に反復作業できるよう、関数を 開発者テストアカウント でも実行できるようになりました

サーバーレス関数の 2026.03 への移行

移行方法は、現在のバージョンによって異なります。

2025.2 から：

1. hsproject.json の platformVersion を "2025.2" から "2026.03" に更新します
2. hs project upload を実行します

2025.1、2023.2、または 2023.1 から：

1. プロジェクトディレクトリで hs project migrate を実行し、プロンプトに従います

レガシーなパブリックアプリ（プロジェクトベースではないアプリ）から：

1. hs app migrate を実行し、プロンプトに従います

移行に関する主な注意事項：

• 古い serverless.json の環境変数は、hs secret add を使用してシークレットとして再登録する必要があります
• 古い単一設定の serverless.json は、src/app/functions/ 内の関数ごとの個別の -hsmeta.json ファイルに置き換えられます

警告： レガシーなプライベートアプリまたはパブリックアプリを 2026.03 に移行すると、元に戻せません。以前のバージョンにダウングレードすることはできません。

エージェントツール（2026.03 で新登場）

エージェントツールは、HubSpot AI エージェント（Breeze Agents）がユーザーに代わってタスクを実行するために呼び出せる、拡張されたカスタムワークフローアクションです。Developer Projects フレームワークを使用して構築します。

エージェントツールの仕組み

• プロジェクト内で拡張された workflowAction タイプとして構築します
• 配布前に審査に提出します
• 承認後、アプリの掲載情報と Breeze Agents を通じて顧客が利用できるようになります
• マーケットプレイス掲載アプリでは、未承認のエージェントツールをデプロイできません。ツールが審査に合格するまでデプロイは失敗します

リスティング要件

エージェントツールを提供するアプリは、エージェントツールのリスティング要件に準拠する必要があります。

詳細については、エージェントツールの概要をご覧ください。

npm Workspaces によるコード共有（2026.03 の新機能）

npm workspaces を使用して、1 つのプロジェクト内の複数の UI 拡張機能（アプリカード、設定ページ、アプリページ）でコードを共有できるようになりました。

セットアップ

拡張機能と同じ階層に共有パッケージを作成します。

my-project-folder/
├── packages/
│   └── shared-utils/
│       ├── index.ts
│       └── package.json
└── src/
    └── app/
        ├── cards/
        │   └── package.json     # declares shared-utils as dependency
        └── pages/
            └── package.json     # declares shared-utils as dependency

各拡張機能の package.json で共有パッケージを参照します。

{
  "dependencies": {
    "shared-utils": "*"
  }
}

インストール

hs project dev または hs project upload の実行時に共有パッケージは自動的にインストールされます。または、次のコマンドで手動でインストールできます。

hs project install-deps

詳細については、npm workspaces によるコード共有をご覧ください。

Developer MCP サーバー（GA）

ローカルの HubSpot Developer MCP サーバーが一般提供され、AI を活用したコードエディター（Claude Code、Cursor、VS Code など）でアプリや CMS を開発できるようになりました。

セットアップ

hs mcp setup

HubSpot CLI v8.2.0 以降が必要です。利用できるツールには、create-project、add-feature-to-project、upload-project、deploy-project、validate-project、search-docs、fetch-doc、get-build-status、get-build-logs などがあります。

ツールの全一覧とセットアップについては、Developer MCP サーバーのドキュメントをご覧ください。

利用可能な UI コンポーネント

@hubspot/ui-extensions からインポートします。

• レイアウト: Flex、Box、Divider、Grid、AutoGrid、Spacer、Inline
• テキスト／表示: Text、Heading、Image、Link、Icon、Illustration
• 入力: Input、TextArea、Select、MultiSelect、Checkbox、RadioButton、DateInput、NumberInput、CurrencyInput、SearchInput、StepperInput、Toggle、ToggleGroup
• アクション: Button、LoadingButton、IconButton、ButtonRow
• フィードバック: Alert、LoadingSpinner、Tag、StatusTag、Badge、Tooltip、ProgressBar、EmptyState、ErrorState
• オーバーレイ: Modal、ModalBody、ModalFooter、Panel、PanelBody、PanelFooter、Dropdown
• データ: Table、TableHead、TableBody、TableRow、TableCell、DescriptionList、Statistics、ScoreCircle
• ナビゲーション: Tabs、StepIndicator、Accordion
• グラフ: BarChart、LineChart
• コンテナー: Tile
• フォーム: Form、FormField
• リスト: List

@hubspot/ui-extensions/crm からインポートします。

• CRM データ: CrmPropertyList、CrmAssociationTable、CrmAssociationPivot、CrmAssociationPropertyList、CrmAssociationStageTracker、CrmDataHighlight、CrmReport、CrmStageTracker、CrmStatistics
• CRM アクション: CrmActionButton、CrmActionLink、CrmCardActions

Webhook の設定

src/app/webhooks/webhooks-hsmeta.json を作成します。

{
  "uid": "my-webhooks",
  "type": "webhooks",
  "config": {
    "settings": {
      "targetUrl": "https://api.example.com/webhook",
      "maxConcurrentRequests": 10
    },
    "subscriptions": {
      "crmObjects": [
        {
          "subscriptionType": "object.creation",
          "objectType": "contact",
          "active": true
        },
        {
          "subscriptionType": "object.propertyChange",
          "objectType": "contact",
          "active": true
        }
      ],
      "legacyCrmObjects": [
        {
          "subscriptionType": "contact.propertyChange",
          "propertyName": "email",
          "active": true
        }
      ],
      "hubEvents": [
        {
          "subscriptionType": "contact.privacyDeletion",
          "active": true
        }
      ]
    }
  }
}

新形式のイベント（object.*）には crmObjects を使用します。contact.creation などの従来型には legacyCrmObjects を使用します。contact.privacyDeletion および conversation.* には hubEvents を使用します。

署名の検証（必須）

HubSpot はすべての送信リクエストに X-HubSpot-Signature-v3 を付与します。

• Webhook の配信 — HubSpot はイベントペイロードを targetUrl に POST します
• カード／設定ページのフェッチ — UI 拡張機能からの hubspot.fetch() 呼び出しはすべて、HubSpot を経由し、署名されます

どちらも @hubspot/api-client の Signature.isValid() を使用して、同じ方法で検証する必要があります。完全な実装については、references/signature-validation.md をご覧ください。

UI 拡張機能用の package.json

{
  "name": "my-card",
  "version": "0.1.0",
  "dependencies": {
    "@hubspot/ui-extensions": "latest",
    "react": "^18.2.0"
  },
  "devDependencies": {
    "typescript": "^5.3.3"
  }
}

インストール: hs project install-deps

配布と認証の概要

配布方法	認証タイプ	インストール上限
private	static	標準アカウント 1 件＋テストアカウント 10 件
private	oauth	許可リストに登録されたアカウント最大 10 件
marketplace	oauth	掲載前は 25 件、掲載後は無制限

App Marketplace への掲載

HubSpot App Marketplace に提出する前に、アプリは次の主要要件を満たす必要があります。

技術面の最低要件：

• OAuth のみを認証方法として使用すること — API キーやプライベートアプリのトークンは使用できません
• 過去 30 日以内に OAuth 認証済みの API アクティビティがある、無関係なアカウントからの有効なインストールが少なくとも 3 件あること
• アプリが実際に使用するスコープのみをリクエストすること。リクエストするすべてのスコープを Shared data テーブルに記載する必要があります
• サポート対象のプラットフォームバージョン（現在は 2025.2 以降、2026.03 を推奨）で動作すること
• 認定アプリでは、サポート対象の日付ベースの API バージョンを使用すること
• 新規掲載／認定ではクラシック CRM カードを使用できません（2026 年 10 月 31 日までに App Cards に移行する必要があります）
• エージェントツールは審査対象の機能です。エージェントツールの掲載要件への準拠についてツールが審査に合格するまで、デプロイは失敗します

掲載内容：

• コンテンツは統合に固有のものである必要があります（一般的な製品マーケティングではありません）
• すべての URL は公開され、誰でもアクセスでき、250 文字未満である必要があります — 提出前にサイトの許可リストに HubSpot Crawler を追加してください
• 次の内容を含めてください：セットアップドキュメント、インストールボタンの URL、サポートリソース、利用規約、プライバシーポリシー、価格（ウェブサイトの記載内容と完全に一致すること）
• 同じオブジェクトについて読み取りスコープと書き込みスコープの両方をリクエストする場合は、双方向同期を Shared data に明記する必要があります

App Cards（UI 拡張機能を使用する場合）：

• カード名やアイコンに HubSpot のブランド名を使用しないでください
• 各サーフェスでプライマリボタンは 1 つにしてください。破壊的な操作を行うボタンには破壊的操作用のスタイルを適用する必要があります
• 機密データにアクセスしたり、表示したりしないでください

**審査プロセス：**初回審査は 10 営業日以内に行われます。全体のサイクルには最大 60 日かかります。同時に審査中にできるアプリは 1 つだけです。

要件チェックリストの全項目については、references/marketplace-listing.md を参照してください。

ローカル開発

hs project dev            # Starts dev server with hot reload

起動すると、テストアカウントにローカル開発ホームページが表示され、有効な開発セッションを確認できます。.jsx／.tsx ファイルへの変更は自動的に再読み込みされます。

注（Chrome 142 以降）：初回起動時に、app.hubspot.com からのローカルネットワークアクセスのポップアップを承認してください。

デバッグ

HubSpot の Development > Monitoring > Logs > UI Extensions でログを確認できます。

コードでは、ロガーを使用します。

import { logger } from "@hubspot/ui-extensions";
logger.info("Info message");
logger.debug("Debug message");
logger.warn("Warning message");
logger.error("Error message");

追加リソース

リファレンスファイル

詳細な設定とパターンについては、次を参照してください。

• references/app-configuration.md — app-hsmeta.json の完全なスキーマ、認証タイプ
• references/scopes.md — カテゴリ（CRM、CMS、設定、マーケティングなど）別にまとめた、利用可能な OAuth スコープの全一覧
• references/ui-extensions-sdk.md — SDK フック、コンテキストフィールド、アクション API
• references/fetching-data.md — hubspot.fetch() の完全ガイド：ネイティブの fetch との違い、制限、自動クエリパラメーター、Authorization ヘッダーのパターン、ローカル開発プロキシ、署名検証
• references/ui-components.md — すべての UI コンポーネントと使用例
• references/features.md — アプリイベント、アプリオブジェクト（オープンベータ）、設定ページ、ホームページ
• references/signature-validation.md — Webhook およびカード／設定ページの fetch エンドポイント向けの、署名検証の完全な実装
• references/marketplace-listing.md — App Marketplace の掲載要件、ブランド規則、アプリカードの基準、審査プロセスの詳細

公式ドキュメント

• アプリを作成する
• アプリ設定のリファレンス
• HubSpot でアプリを管理する
• UI 拡張機能の概要
• アプリカードのリファレンス
• UI 拡張機能 SDK
• データの取得
• UI コンポーネントの概要
• アプリページ（旧アプリホーム）
• 設定ページ
• アプリイベント（ベータ）
• アプリオブジェクト（ベータ）
• Webhook を設定する
• アプリマーケットプレイスへの掲載要件
• アプリの掲載方法
• アプリ認定要件
• サーバーレス関数の概要
• エージェントツールの概要
• エージェントツールの掲載要件
• npm workspaces を使ったコード共有
• 開発者向け MCP サーバーのセットアップ
• MCP Auth Apps（リモート MCP サーバーとの統合）
• 2026.03 への移行
• プラットフォームのバージョン管理