【初心者向け】HubSpot CMSでReactモジュール開発！ローカルサーバーではじめる新しいテーマ作り

はじめに 🌿

2025 Spring Spotlightで発表された「HubSpot CMSでのReactローカルサーバーアップデート」…✨そのニュースを見て、もう「これはやってみたいっ！」って感じでした

（なんかよくわからないがすごそう）

だけどそのとき、実はReactほぼはじめまして状態。HTML→CSS→HubL/JS まできたけど、Reactの世界には一歩も踏み込めてなかったんだよね（小声）🙈

でも大丈夫。チュートリアルと格闘しながら、少しずつ「React×HubSpot CMS」が見えてきたので、この記事でシェアしてみますっ💻💖

この記事でわかること ✏️

• HubSpot CMSでReactを使うってどういうこと？🌀

• Spring Spotlightで追加されたローカルサーバー機能って何？🔧

• React初心者がつまずいたポイント＆解決策💥

結論 🎯

✨HubSpot CMSは、Reactモジュールをローカル開発サーバー（local development server）で編集→確認→アップロードできるようになって、 初心者でも「Reactモジュールが作れた！」って実感できるくらい快適で優しい環境になった！！🌈

Reactの知識がちょっとずつでもあれば、自分だけの動的なモジュールが作れちゃうよ〜！

Reactってなに？🌀

Reactは、Facebookが開発した「UI（見た目）を部品のように組み立てられるJavaScriptライブラリ」。

• HTML を JavaScriptの中に書ける「JSX」っていう記法が特徴的！

• 状態（state）を使って、動きのあるUIがつくれる✨

• コンポーネント単位で管理するから、再利用性バツグン！

HubSpot CMSでは、今まではHTML中心（厳密にいうとHubLって言語）+JS だったけど、Reactを使うとより「インタラクティブな動き」が作りやすくなるということみたい💭

やり方 🛠️

前提：

• HubSpot CLI をグローバルでインストールしておく（特定ディレクトリへのローカルインストールだと、手順1で実行する npx @hubspot/create-cms-theme@latest コマンドが失敗する⚡）

• しかし、hs init はしないでおく！（すでに hubspot.config.yml があるなら一旦削除推奨。create-cms-theme の実行でエラーがでるので注意！）

1：テーマを作成する

テーマを作るフォルダを用意して、npx @hubspot/create-cms-theme@latest を実行！💻

(基本的には指示通りに入力したり、処理を眺めてればOK)

(CLIインストールしてますがな‥)

(hs init をさせられている。ここですでにinit済みの環境だと、hs init できなかった！とすねてくる)

(ここまでくれば安心)

作成されたテーマは👇の構成になっているよ：

my-cms-theme/
│── node_modules/
├── src/theme/
│   ├── assets/
│   ├── components/
│   │   └── modules/
│   ├── node_modules/
│   ├── styles/
│   ├── templates/
│   ├── fields.json
│   ├── Globals.d.ts
│   ├── package.json
│   ├── theme.json
│   └── tsconfig.json
│── .prettierrc
│── hsproject.json
└── package.json

ざっくり説明すると：

• assets/：画像などのアセット類

• components/modules/：ReactモジュールのJSXファイルなど

• styles/：CSSファイル

• templates/：HubLテンプレートファイル群

2：ローカルサーバに接続

作成されたテーマのディレクトリに移動して、npm run start を実行。 これでローカルサーバーが立ち上がるよ！🌐

(モジュールやテンプレートとしてなにがあるかがダッシュボードに表示されているね)

3：ローカルでいろいろと変更してみよう

モジュールの index.jsx を書き換えたり、CSSやテンプレートを変更してみよう✨

まず、テーマを作成した時点で /components/modules/GettingStarted/index.jsx というモジュールファイルが含まれているよ。 これを /MyfirstModule/index.jsx として複製すれば、オリジナルのモジュールとしてカスタマイズできる！

モジュールファイルの構成（例）

// モジュール用のフィールドコンポーネントを読み込み
import {
  ModuleFields,
  TextField,
  RichTextField,
  ImageField,
} from '@hubspot/cms-components/fields';

// CMSコンポーネントやCSS、画像を読み込む
import { RichText } from '@hubspot/cms-components';
import logo from '../../../assets/sprocket.svg';
import styles from '../../../styles/getting-started.module.css';

// 表示コンポーネントを定義
export function Component({ fieldValues, hublParameters }) {
  const { src, alt, width, height } = fieldValues.logo;
  const { brandColors } = hublParameters;

  return (
    <div
      className={styles.wrapper}
      style={{ backgroundColor: brandColors?.color, opacity: brandColors?.opacity }}
    >
      <img src={src} alt={alt} width={width} height={height} />
      <h1>{fieldValues.headline}</h1>
      <RichText fieldPath="gettingStarted" />
      <div className={styles.buttons}>
        <a href="https://github.com/HubSpot/cms-react/tree/main/examples">Examples</a>
        <a href="https://github.hubspot.com/cms-react/">Read the Docs</a>
      </div>
    </div>
  );
}

// 初期値の定義
const richTextFieldDefaultValue = `
  <div>
    <div>
      <span>Deploy to your theme by running <pre>npm run deploy</pre> from the root directory</span>
    </div>
  </div>
`;

// フィールドの構造
export const fields = (
  <ModuleFields>
    <ImageField name="logo" label="Logo" default={{ src: logo, height: 100, alt: 'HubSpot logo' }} resizable={true} />
    <TextField name="headline" label="Headline" default="Getting Started with CMS React" />
    <RichTextField name="gettingStarted" label="Getting Started" default={richTextFieldDefaultValue} />
  </ModuleFields>
);
// モジュールのラベル
export const meta = {
  label: 'Getting Started with CMS React',
};

たとえば、見出しの Getting Started with CMS React を変更したいときは、<TextField /> の default="..." を書き換えればOK🍪

CSS ファイル

CSSファイルは import styles from '../../../styles/getting-started.module.css'; のように読み込まれているので、 これを複製して背景色やフォントを変えてみると、見た目の違いがすぐに体感できるよ👩‍🎨

テンプレートファイル

ページテンプレートは templates/page.hubl.html にあり、これは普段どおりHubLで書かれているから安心！ このテンプレートを複製＆編集して、新しく作ったモジュールを表示するように変更すれば、 Reactモジュールがページ上でどう表示されるかもばっちり確認できるよ✏️

(見慣れた光景)

4：HubSpot にアップロードしてみよう

hs project upload で、テーマ全体をCMSにアップロード！ Reactモジュールも含めてプロジェクトとして反映されるよ📦

5：ページを作ってみよう

• 今回作ったテーマで新しいページを作成。

• モジュールが表示されていれば大成功！🎉

注意ポイント ⚡

わたしがつまづいたところをいくつか紹介：

• HubSpot CLI のバージョン：HubSpot CLI v7 に移行していたんだけど、テーマ作成のコマンドは hs init を求めてくるので地味に対応していないのかも？（なのでまずは v6 で進めるのがよさそう）

• 文字化け：モジュール単体のプレビューではOKなのに、ページテンプレートに埋め込むと日本語や絵文字が 〹 みたいに化けちゃうことが…！→本番ページでは問題なしだったから焦らなくてOKだった！

• ReactのJSがビルド＆アップロードされてなかった：hs project uploadを忘れると何も表示されない！

まとめ ✨

HubSpotでReactがこんなにサクッと動くなんて…ちょっと前では考えられなかったよね！✨ ローカル開発サーバー機能のおかげで「コード書く→確認→修正」がスムーズになって、 React初心者の私でも、ちゃんと自分のモジュールが作れたよ〜！！🧁💻

この記事が、これからReact×HubSpot CMSをはじめる誰かの背中をちょっとでも押せたらうれしいな〜っ🌱

あわせて読みたい 📖

• Intro to React for HubSpot Developers

• Quickstart: Build a React + HubL theme

• Updates to CMS React (Spring Spotlight 2025)