HubSpot CMSを使用している場合、カスタムモジュールは習得すべき最も重要なスキルです。クリーンで高速、かつ保守しやすいコードを保ちながら、コンテンツ編集者にページコンテンツの完全な制御を提供します。
しかし、ここに問題があります — ほとんどのHubSpot開発者はモジュールを間違った方法で構築しています。肥大化したCSSを書き、フィールドのグループ化をスキップし、見出しタグをハードコードし、パフォーマンスを完全に無視しています。その結果はどうなるでしょうか？ページの読み込みが遅くなり、編集者は不満を抱き、誰も保守したくないような乱雑なコードになってしまいます。
このガイドでは、HubSpotで本番環境で使えるカスタムモジュールを正しい方法で構築するために必要なすべてを網羅しています。実際のコード例、適切なフィールド構造、HubLのベストプラクティス、そして実際に役立つパフォーマンス向上のヒントを紹介します。
カスタムモジュールは、デザインマネージャー内の4つのファイルで構成される再利用可能なコンテンツブロックです：
レゴブロックを組み立てるようなものだと考えてください。すべての適切な接続ポイントを備えたものを一度設計すれば、コンテンツ編集者はコードに一切触れることなく、任意のページの任意のセクションでそれを使用できます。
何かを構築する前に、モジュールを適切に設定してください。以下は、ヒーローセクションモジュール用のクリーンな meta.json の例です：
ここで注目すべき点が2つあります。第一に、host_template_types はこのモジュールを使用できる場所を制御します。ページ専用モジュールの場合は PAGE に設定し、ブログテンプレートでも機能させる必要がある場合は BLOG_POST を含めます。モジュールがCSSまたはJSを使用している場合は、電子メールテンプレート用に許可したままにしないでください（電子メールはこれらをサポートしていません）。第二に、常に意味のある help_text を追加してください。これはデザインマネージャーに表示され、チームがコードを読まなくてもモジュールの機能や目的を理解するのに役立ちます。
fields.json ファイルは、ほとんどの開発者が失敗する場所です。15以上のフィールドが平坦にリストされていると、編集作業が苦痛になります。関連するフィールドをグループ化することで、クリーンで直感的なインターフェースが作成されます。
コンテンツフィールドの前に、すべてのモジュールにはセクション設定グループが必要です。これにより、コンテンツ編集者はセクションのID、カスタムクラス、および表示/非表示を制御できます：
これがなぜ重要なのでしょうか？コンテンツ編集者は多くの場合、セクションを一時的に非表示にしたり、ナビゲーション用のアンカーリンクを追加したり、特別なスタイリング用のカスタムクラスを適用したりする必要があります。これらのフィールドがないと、小さな変更のたびに開発者に依頼しなければなりません。これらがあれば、彼らは自立して作業できます。
見出しタグをハードコードしないでください。編集者がSEOの階層を制御できるように、常に選択フィールドを提供してください：
デフォルトの見出しタグが h1 ではなく h2 に設定されていることに注目してください。これは意図的なものです。ほとんどのページには H1 が1つしかなく、それは通常、最初のモジュールによって処理されます。それ以降のすべてのモジュールはデフォルトで H2 になるべきです。編集者がこのモジュールをページの最初のセクションとして配置した場合、彼ら自身で H1 に切り替えることができます。
よくある間違いは、すべてのボタンにHubSpotのCTAモジュールを使用することです。CTAは強力ですが、トラッキングのオーバーヘッドが追加され、使いすぎるとページの読み込みが遅くなります。ほとんどのボタンにおいて、シンプルなテキストフィールド付きのリンクフィールドがあれば十分です：
リンクフィールドタイプは、URL、新しいタブで開く、nofollow のオプションを編集者に自動的に提供します。これらすべてを、開発者の追加作業なしで実現できます。
フィールドの命名方法は、あなたが考えている以上に重要です。コンテンツ編集者は、ページを編集するたびにこれらのラベルを目にします。具体的に記述してください：
また、すべてのフィールドに help_text を追加してください。今書く10単語の説明が、後々の10分間のSlackでの会話を省いてくれます。
それでは、実際の module.html を構築しましょう。ここで、すべてのフィールドが1つのレンダリングされたコンポーネントとして統合されます。
このコードで使用されている重要なパターンを分解してみましょう。
上記のコードのすべての HubL タグは、 の代わりにダッシュ構文 を使用しています。この1つの変更が、レンダリングされるHTMLに大きな違いをもたらします。
ダッシュがないと、HubLはタグを処理する場所に空白行を挿入します。ページのソースコードは不要な空白でいっぱいになり、すべての要素の間に空行ができます。これにより、HTMLが重くなり、デバッグが難しくなり、解析もわずかに遅くなります。
ダッシュを使用すると、HubLはその空白をきれいに取り除きます。レンダリングされたHTMLは無駄がなく、最小限で、ブラウザが必要とする通りのものになります。20以上のモジュールがあるページでは、HTMLのファイルサイズを著しく削減できます。
変数の出力にも同じことが言えます。動的な値の周囲に空白ができないように、 の代わりに を使用してください。
見出しは、フィールドの値を直接HTMLタグとして使用します：
編集者がドロップダウンから「H2」を選択すると、これは適切な <h2> タグとしてレンダリングされます。「H1」を選択すると、<h1> としてレンダリングされます。編集者は開発者を必要とせずに、完全なSEO制御を持っています。
コンテンツの各セクションは if チェックでラップされています。見出しフィールドが空の場合、<h2> タグはレンダリングされません。ボタンテキストが空の場合、ボタンは表示されません。画像にソースがない場合、画像の列は完全に消えます。
これにより、空のHTML要素がページに表示されるのを防ぎます。レイアウトの崩れや、スペースを占有する空のdiv、空の見出しタグによるアクセシビリティの問題が発生しません。
HubSpotの画像フィールドタイプを使用する場合は、常にフィールドの値を直接出力してください（src、alt、width、height）。HubSpotの画像フィールドはすでにSEOに最適化されています。レスポンシブ画像属性と適切な代替テキスト（alt）の処理が標準で提供されます。
これらの値をハードコードされた属性で上書きしないでください。スクロールせずに見える範囲（アバブ・ザ・フォールド）より下にある画像には loading="lazy" を追加するだけで、ページのパフォーマンスが向上します。
すべてのモジュールでセクション設定（ID、クラス、表示/非表示）が必要な場合、そのコードをすべての module.html にコピーするべきではありません。代わりに、マクロファイルを1度だけ作成し、それをどこにでもインポートします。
一度書けば、50個のモジュールにインポートできます。セクションIDの仕組みを変更する必要がある場合は、1つのファイルを更新するだけで、すべてのモジュールに更新が反映されます。これがプロフェッショナルなHubSpotテーマの構築方法です。
これは、このガイド全体の中で最も重要なセクションかもしれません。ほとんどのHubSpot開発者は、各モジュールの module.css ファイル内にCSSを書きます。これは混乱を招きます。モジュール間でのスタイルの重複、一貫性のない間隔、ファイルサイズの増大、そして新しいモジュールが追加されるたびにページの読み込みが遅くなります。
上記の module.html を見てください。カスタムCSSはゼロです。すべてのスタイルは、HTML内のTailwindユーティリティクラスを通じて直接適用されています：
このアプローチの利点：
module.css を書く唯一のタイミングは、Tailwindではどうしても処理できない場合です。通常は、カスタムアニメーションや複雑な疑似要素のパターンです：
それ以外のすべては、グローバルなテーマCSSに含めるか、Tailwindのユーティリティで処理されるべきです。例外はありません。
同じルールが module.js にも適用されます。ほとんどのモジュールはJavaScriptを全く必要としません。
JSが不要なモジュール：ヒーローセクション、テキストと画像ブロック、機能グリッド、お客様の声（テスティモニアル）カード、価格表、フッターセクション。これらは純粋に視覚的なものであり、HTMLとCSSがすべてを処理します。
JSが必要なモジュール：アコーディオン、カルーセル/スライダー、タブコンポーネント、モーダルポップアップ、フォーム検証、スクロールでトリガーされるアニメーション。
JavaScriptを書く場合は、バニラ（依存関係なし）にしてください。2026年にjQueryは不要です。HubSpotは、1つのページにモジュールが複数回表示されても、モジュールタイプごとに1回だけ module.js を読み込みます。しかし、それでもページの重みには追加されます。含めるすべてのスクリプトについて意図を持ってください。
Googleは検索ランキングにおいてアクセシビリティのシグナルを考慮しています。アクセシブルなモジュールを構築することは、単なる良い習慣ではなく、SEOに直接影響を与えます。
Tailwind CSSを使用している場合、すでに有利です。Tailwindのデフォルトのカラーパレットは、適切なコントラスト比で設計されています。これらの安全な組み合わせに固執してください：
明るい背景に明るいテキストは避けてください。4.5:1 未満のコントラスト比は WCAG AA に不合格となり、検索ランキングに悪影響を与える可能性があります。
モジュールを公開する前に、以下のチェックリストを実行してください：
すべてのモジュールにCSSを書くこと。 これにより、スタイルの重複とページ読み込みの重大化が生じます。Tailwindユーティリティクラスを使用するか、テーマのスタイルシートにグローバルCSSを記述してください。モジュールのCSSは最終手段であるべきです。
不必要にJavaScriptを追加すること。 ヒーローセクション、機能グリッド、お客様の声などの静的コンテンツモジュールにはJavaScriptは必要ありません。すべてのスクリプトがページの重さを増大させます。
見出しタグをハードコードすること。 HTMLに直接 <h2> と書くと、コンテンツ編集者はSEOの階層を制御できません。常に選択フィールドを使用し、タグを動的にレンダリングしてください。
HubLの空白を無視すること。 の代わりにを使用すると、レンダリングされたHTMLが空白行でいっぱいになります。ダッシュ構文は空白を削除し、よりクリーンで軽量な出力を生成します。
グループ化されていない平坦なフィールドリスト。 ページエディターで20個のグループ化されていないフィールドがあると、コンテンツ編集者にとって悪夢です。コンテンツ、画像、ボタン、セクション設定など、関連するフィールドをグループ化して、インターフェースをクリーンでナビゲートしやすくしてください。
セクション設定をスキップすること。 IDフィールドがないと、編集者はアンカーリンクを作成できません。表示/非表示の切り替えがないと、セクションを一時的に隠すことができません。カスタムクラスフィールドがないと、スタイルの微調整のたびに開発者が必要になります。これら3つのフィールドを標準的な実践としてすべてのモジュールに追加してください。
HubSpotの画像スニペットを上書きすること。 HubSpotの画像フィールドタイプは、適切な src、alt、width、height、およびレスポンシブ属性を備えたSEO最適化済みの出力をすでに生成します。これをカスタムコードで置き換えないでください。フィールドの値を直接出力し、適切な場合は loading="lazy" を追加するだけにしてください。
すべてのボタンにCTAを使用すること。 HubSpotのCTAにはトラッキングのオーバーヘッドがあります。ページにリンクするシンプルなボタンの場合は、代わりにテキストフィールドとリンクフィールドを備えたアンカータグを使用してください。CTAは、トラッキングと分析が本当に必要なボタンのために予約しておいてください。
HubSpotでカスタムモジュールを構築することは、単に見栄えを良くすることだけではありません。高速で、アクセシブルで、SEOに優れ、コンテンツ編集者が簡単に使用できるコンポーネントを構築することです。
このガイドで取り上げたテクニック — グループ化されたフィールド、動的な見出しタグ、HubLの空白制御、Tailwindユーティリティクラス、再利用可能なマクロ、および適切な画像処理 — こそが、プロフェッショナルなHubSpot開発と素人の仕事を分けるものです。
次のモジュールからこれらの実践を適用し始めてください。コンテンツ編集者はあなたに感謝し、ページの読み込みは速くなり、SEOスコアは向上するでしょう。
HubSpotモジュールをゼロから構築するには時間がかかります。Rapid を使用すると、任意のUIスクリーンショットをアップロードして、fields.json、HubLバインディング、および適切な構造を備えた完全に本番環境ですぐに使えるHubSpotモジュールを60秒未満で生成できます。無料で試す →