HubSpot CMSの全体像と
開発環境構築

HubSpot CMS とは何か — 他CMSとの比較

HubSpot CMS（Content Management System）は、 HubSpotが提供するクラウド型のウェブサイト構築・管理プラットフォームです。 他のCMSと最も異なる点は、CRM（顧客管理）・マーケティング・営業ツールと同一プラットフォーム上に存在することです。 サイトに訪れた人がフォームを送信した瞬間に、コンタクトレコードが作られ、 ワークフローが動き、担当営業に通知が届く——この一気通貫の仕組みが最大の強みです。

HubSpot CMS と他CMSの特性比較

HubSpot CMS を選ぶべきケース

• BtoB マーケティングサイト：リード獲得・ナーチャリング・商談管理まで一元化したい場合に最適。フォームからCRMへの自動連携・ワークフロー・メール配信がすぐ使える。
• マーケターが自走したい：ブログ記事・LP・フォームをエンジニアなしで作成・更新したい。HubSpotのページエディターは非エンジニアにも使いやすい。
• パーソナライズが必要：既知のコンタクト（リード・顧客）に対して、ライフサイクルステージ・業種・行動履歴に基づいたコンテンツを表示したい。
• インフラ管理コストを下げたい：サーバー・セキュリティパッチ・CDN設定をHubSpotに任せることで、運用の技術的負荷を下げたい。

プラン比較と選定の考え方

HubSpot CMS は利用プランによって使える機能が大きく異なります。 開発前にクライアントのプランを確認し、何が使えて何が使えないかを把握することが設計の起点になります。

プランに応じた設計の変更点

開発用ポータル（Developer Account）の取得

HubSpot では無料の Developer Accountを作成できます。 Developer Account は本番相当の機能をほぼすべて使えるサンドボックス環境で、 クライアントのポータルに触れる前に開発・検証を行うための必須の環境です。

Developer Account の取得手順

Personal Access Key の発行

CLI でポータルにアクセスするために Personal Access Key が必要です。 Developer Account 作成後、以下の手順で発行します。

• HubSpot 管理画面の右上のプロフィールアイコン → 「プロフィールと設定」
• 左メニューから「インテグレーション」→「個人用アクセストークン」
• 「個人用アクセストークンを作成」をクリック
• 必要なスコープを選択：CMS（デザインマネージャー） と コンテンツ は必須
• 生成されたキーをコピーして安全な場所に保存する

管理画面の構造と開発者が使う画面

HubSpot の管理画面は多機能なため、最初は迷いやすいです。 開発者として最低限把握しておくべき画面を整理します。

開発環境の構築（Node.js / CLI / エディタ）

必要なツールのインストール

# ===== Step 1: Node.js のバージョン確認（20以上が必要）=====
$ node --version
v20.11.0   ← 20以上であることを確認（18.x は NG）

# nvm を使ったバージョン管理（推奨）
$ nvm install 20
$ nvm use 20

# ===== Step 2: HubSpot CLI インストール =====
$ npm install -g @hubspot/cli
$ hs --version
5.x.x   ← インストール確認

# ===== Step 3: プロジェクトフォルダ作成 =====
$ mkdir my-company-hubspot
$ cd    my-company-hubspot
$ git init
$ npm init -y

# ===== Step 4: HubSpot CLI 認証 =====
$ hs init
? Enter a name for this account: my-company-dev
? Enter your HubSpot portal ID: 12345678
? How would you like to authenticate?
  ❯ Personal Access Key (recommended)
? Enter your personal access key: eu1-xxxx-xxxx-xxxx
✔ Authenticated! Config saved to hubspot.config.yml

# ===== Step 5: .gitignore を作成 =====
$ echo "hubspot.config.yml" >> .gitignore
$ echo "node_modules/"      >> .gitignore
$ echo ".DS_Store"          >> .gitignore

# ===== Step 6: テーマの雛形を生成 =====
$ mkdir src
$ hs create theme my-theme --path=./src
✔ Theme created at ./src/my-theme

VS Code の推奨設定

{
  "recommendations": [
    "HubSpot.hubl",              // HubL シンタックスハイライト・補完
    "esbenp.prettier-vscode",    // コードフォーマッター
    "dbaeumer.vscode-eslint",    // JavaScript lint
    "bradlc.vscode-tailwindcss", // Tailwind 使う場合
    "streetsidesoftware.code-spell-checker" // スペルチェック
  ]
}

{
  // .html ファイルを HubL として認識させる
  "files.associations": {
    "*.html": "hubl"
  },
  // 保存時にフォーマット
  "editor.formatOnSave": true,
  // インデントは2スペース
  "editor.tabSize": 2,
  "editor.insertSpaces": true
}

テーマのディレクトリ設計

実案件のコードベース分析（741モジュール・964テンプレートを持つ大規模プロジェクト）から、 実務で機能する最適なディレクトリ構成を導き出しました。 以下が推奨する標準構成です。

推奨ディレクトリ構成

theme.json によるデザイントークンの設計

theme.json は HubSpot テーマの設定ファイルです。 ここで定義した値はHubSpotの管理画面でノーコードで変更でき、 CSS 変数として全テンプレート・全モジュールで参照できます。 「デザインの一元管理の起点」として最も重要なファイルです。

theme.json の全体構成

{
  "label": "My Company Theme",
  "preview_path": "./templates/page.html",
  "screenshot_path": "./images/screenshot.png",
  "enable_domain_stylesheets": false,
  "hide_all_default_modules": true,
  // ↑ HubSpotデフォルトモジュールをページエディタに表示しない
  //   カスタムモジュールのみ使わせる場合は true にする

  "fields": [

    // ===== カラー =====
    {
      "type": "group",
      "name": "colors",
      "label": "カラー設定",
      "children": [
        {
          "type": "color",
          "name": "primary_color",
          "label": "プライマリカラー",
          "default": { "color": "#0052CC", "opacity": 100 }
        },
        {
          "type": "color",
          "name": "secondary_color",
          "label": "セカンダリカラー",
          "default": { "color": "#FF5630", "opacity": 100 }
        },
        {
          "type": "color",
          "name": "text_color",
          "label": "テキストカラー",
          "default": { "color": "#2d3748", "opacity": 100 }
        },
        {
          "type": "color",
          "name": "bg_color",
          "label": "ページ背景色",
          "default": { "color": "#ffffff", "opacity": 100 }
        }
      ]
    },

    // ===== タイポグラフィ =====
    {
      "type": "group",
      "name": "typography",
      "label": "タイポグラフィ",
      "children": [
        {
          "type": "font",
          "name": "heading_font",
          "label": "見出しフォント",
          "default": {
            "font": "Noto Sans JP",
            "font_set": "GOOGLE",
            "variant": "700",
            "size": "36px",
            "color": "#1a202c"
          }
        },
        {
          "type": "font",
          "name": "body_font",
          "label": "本文フォント",
          "default": {
            "font": "Noto Sans JP",
            "font_set": "GOOGLE",
            "variant": "400",
            "size": "16px",
            "color": "#2d3748"
          }
        }
      ]
    },

    // ===== スペーシング・レイアウト =====
    {
      "type": "group",
      "name": "layout",
      "label": "レイアウト設定",
      "children": [
        {
          "type": "number",
          "name": "container_max_width",
          "label": "コンテナ最大幅（px）",
          "default": 1200
        },
        {
          "type": "number",
          "name": "section_padding_v",
          "label": "セクション上下余白（px）",
          "default": 80
        },
        {
          "type": "number",
          "name": "border_radius",
          "label": "角丸（px）",
          "default": 8
        }
      ]
    }
  ]
}

theme.json の値を CSS 変数として展開する

theme.json で定義した値は、HubL を使って CSS 変数として展開します。 全テンプレートの <head> 内か、グローバル CSS の冒頭で定義します。

/* theme.json の値を CSS 変数として展開する
   HubL の theme 変数でアクセスする */
:root {
  /* ===== カラー ===== */
  --color-primary   : {{ theme.colors.primary_color.color }};
  --color-secondary : {{ theme.colors.secondary_color.color }};
  --color-text      : {{ theme.colors.text_color.color }};
  --color-bg        : {{ theme.colors.bg_color.color }};

  /* ===== タイポグラフィ ===== */
  --font-heading    : {{ theme.typography.heading_font.font }}, sans-serif;
  --font-body       : {{ theme.typography.body_font.font }}, sans-serif;
  --font-size-base  : {{ theme.typography.body_font.size }};

  /* ===== レイアウト ===== */
  --container-max   : {{ theme.layout.container_max_width }}px;
  --section-padding : {{ theme.layout.section_padding_v }}px;
  --border-radius   : {{ theme.layout.border_radius }}px;

  /* ===== ブレークポイント（固定値・CSS変数はメディアクエリ内で使えないため参照用）===== */
  --bp-sm  : 480px;
  --bp-md  : 768px;
  --bp-lg  : 1024px;
  --bp-xl  : 1280px;
}

グローバル CSS 設計（ITCSS アプローチ）

実案件のコードベース分析では、グローバル CSS が ITCSS（Inverted Triangle CSS）に近い 層構造で設計されていることが確認されました。 ITCSS は「抽象→具体」「広範囲→局所」の順にCSSを定義する設計思想で、 スタイルの上書き問題や詳細度の衝突を防ぎます。

ITCSS 層構造

/* ===== Objects: レイアウトパターン =====
   デザイン（色・フォント）は持たない。構造のみ定義する。
===================================================== */

/* コンテナ */
.container {
  width: 100%;
  max-width: var(--container-max);
  margin-inline: auto;
  padding-inline: 20px;
}
@media (min-width: 768px)  { .container { padding-inline: 32px; } }
@media (min-width: 1280px) { .container { padding-inline: 40px; } }

/* セクション */
.section {
  padding-block: var(--section-padding);
}
.section--sm { padding-block: calc(var(--section-padding) * 0.5); }
.section--lg { padding-block: calc(var(--section-padding) * 1.5); }

/* グリッド */
.grid { display: grid; gap: var(--gap, 24px); }
.grid-2 { grid-template-columns: repeat(2, 1fr); }
.grid-3 { grid-template-columns: repeat(3, 1fr); }
.grid-4 { grid-template-columns: repeat(4, 1fr); }

@media (max-width: 768px) {
  .grid-2, .grid-3, .grid-4 { grid-template-columns: 1fr; }
}
@media (min-width: 480px) and (max-width: 1024px) {
  .grid-3, .grid-4 { grid-template-columns: repeat(2, 1fr); }
}

最初のテーマをアップロードする

環境が整ったら、テーマをHubSpotにアップロードして動作を確認します。 以下の手順で最初のアップロードから確認までを完了させます。

# ===== 初回：全ファイルをアップロード =====
$ hs upload src/my-theme @my-theme --portal=dev
Uploading "src/my-theme" to "@my-theme" on portal "dev"...
✔ Done! Uploaded 12 files.

# ===== 開発中：watch モードで自動同期 =====
$ hs watch src/my-theme @my-theme --portal=dev
Watcher started, watching "src/my-theme"
# ファイルを保存するたびに自動アップロードされる

# ===== アップロード後の確認 =====
# HubSpot管理画面 → マーケティング → デザインマネージャー
# 左ペインに @my-theme が表示されれば成功

# ===== ページにテンプレートを適用して確認 =====
# ウェブサイトページ → 新しいページを作成
# → テンプレートに "page.html" を選択
# → プレビューで表示を確認

{
  "name": "my-company-hubspot",
  "scripts": {
    "dev"          : "hs cms watch src/my-theme @my-theme --portal=dev",
    "deploy:dev"   : "hs cms upload src/my-theme @my-theme --portal=dev --overwrite",
    "deploy:prod"  : "hs cms upload src/my-theme @my-theme --portal=prod --overwrite",
    "lint"         : "hs lint src/my-theme --portal=dev",
    "predeploy:prod": "npm run lint"
  },
  "devDependencies": {
    "@hubspot/cli": "^8.0.0"  // CLI v8以上（Node 20必須）
  }
}

第1章まとめ