Big picture of HubSpot CMS
Development environment construction

What is HubSpot CMS? Comparison with other CMS

HubSpot CMS (Content Management System) A cloud-based website construction and management platform provided by HubSpot. The biggest difference from other CMS is thatExists on the same platform as CRM (customer management), marketing, and sales toolsThat's it. A contact record is created the moment someone visits your site and submits a form. The workflow moves and notifications are sent to the sales person in charge—this all-in-one system is its greatest strength.

Comparison of characteristics of HubSpot CMS and other CMS

When to choose HubSpot CMS

• BtoB marketing site:Ideal if you want to centralize lead acquisition, nurturing, and business negotiation management. Automatic linkage, workflow, and email delivery from forms to CRM can be used immediately.
• Marketers want to be autonomous:I want to create and update blog articles, LPs, and forms without an engineer. HubSpot's page editor is easy to use even for non-engineers.
• Requires personalization:I want to display content based on lifecycle stage, industry, and behavior history to known contacts (leads/customers).
• Want to lower infrastructure management costs:I want to reduce the technical burden of operations by leaving server, security patches, and CDN settings to HubSpot.

Concept of plan comparison and selection

The features available with HubSpot CMS vary greatly depending on the usage plan. Check the client's plan before development,What can and cannot be usedUnderstanding this is the starting point for design.

Design changes depending on the plan

Obtaining a development portal (Developer Account)

At HubSpotFree Developer Accountcan be created. The Developer Account is a sandbox environment where you can use almost all the functions equivalent to production. This is an essential environment for development and verification before touching the client's portal.

Steps to obtain a Developer Account

Issuing a Personal Access Key

A Personal Access Key is required to access the portal via the CLI. After creating a Developer Account, issue it using the following steps.

• Your profile icon in the top right corner of your HubSpot admin screen → Profile & Settings
• From the left menu, select “Integration” → “Personal Access Token”
• Click "Create a personal access token"
• Select the required scope:CMS (design manager) and content is required
• Copy the generated key and save it in a safe place

Structure of the management screen and screens used by developers

HubSpot's admin screen is multi-functional, so it's easy to get lost at first. We will organize the screens that you should at least understand as a developer.

Building a development environment (Node.js / CLI / editor)

Installing the necessary tools

# ===== Step 1: Check Node.js version (requires 20 or higher) =====
$ node --version
v20.11.0 ← Confirm that it is 20 or higher (18.x is NG)

# Version control using nvm (recommended)
$ nvm install 20$ nvm use 20# ===== Step 2: HubSpot CLI installation =====
$ npm install -g @hubspot/cli
$ hs --version
5.x.x ← Installation confirmation

# ===== Step 3: Create project folder =====
$ mkdir my-company-hubspot
$ cd    my-company-hubspot
$ git init$ npm init -y

# ===== Step 4: HubSpot CLI authentication =====
$ 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: Create .gitignore =====
$ echo "hubspot.config.yml" >> .gitignore$ echo "node_modules/"      >> .gitignore$ echo ".DS_Store"          >> .gitignore# ===== Step 6: Generate theme template =====
$ mkdir src$ hs create theme my-theme --path=./src
✔ Theme created at ./src/my-theme

Recommended settings for VS Code

{
  "recommendations": [
    "HubSpot.hubl",              // HubL syntax highlighting/completion
    "esbenp.prettier-vscode",    // code formatter
    "dbaeumer.vscode-eslint",    // JavaScript lint
    "bradlc.vscode-tailwindcss", // When using Tailwind
    "streetsidesoftware.code-spell-checker" // spell check
  ]
}

{
  // Recognize .html files as HubL
  "files.associations": {
    "*.html": "hubl"
  },
  // Format on save
  "editor.formatOnSave": true,
  // Indentation is 2 spaces
  "editor.tabSize": 2,
  "editor.insertSpaces": true
}

Theme directory design

From codebase analysis of an actual project (a large-scale project with 741 modules and 964 templates), We have derived the optimal directory structure that works in practice. The following is the recommended standard configuration.

Recommended directory structure

Designing design tokens with theme.json

theme.json is the HubSpot theme's configuration file. The values defined here can be changed with no code on the HubSpot admin screen. It can be referenced as a CSS variable in all templates and all modules. “The starting point for unified management of design”This is the most important file.

Overall structure of 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,
  // ↑ Do not display HubSpot default module in page editor
  // Set to true if you want to use only custom modules

  "fields": [

    // ===== Color =====
    {
      "type": "group",
      "name": "colors",
      "label": "Color settings",
      "children": [
        {
          "type": "color",
          "name": "primary_color",
          "label": "Primary color",
          "default": { "color": "#0052CC", "opacity": 100 }
        },
        {
          "type": "color",
          "name": "secondary_color",
          "label": "Secondary Color",
          "default": { "color": "#FF5630", "opacity": 100 }
        },
        {
          "type": "color",
          "name": "text_color",
          "label": "Text Color",
          "default": { "color": "#2d3748", "opacity": 100 }
        },
        {
          "type": "color",
          "name": "bg_color",
          "label": "Page background color",
          "default": { "color": "#ffffff", "opacity": 100 }
        }
      ]
    },

    // ===== Typography =====
    {
      "type": "group",
      "name": "typography",
      "label": "typography",
      "children": [
        {
          "type": "font",
          "name": "heading_font",
          "label": "Heading font",
          "default": {
            "font": "Noto Sans JP",
            "font_set": "GOOGLE",
            "variant": "700",
            "size": "36px",
            "color": "#1a202c"
          }
        },
        {
          "type": "font",
          "name": "body_font",
          "label": "Body font",
          "default": {
            "font": "Noto Sans JP",
            "font_set": "GOOGLE",
            "variant": "400",
            "size": "16px",
            "color": "#2d3748"
          }
        }
      ]
    },

    // ===== Spacing Layout =====
    {
      "type": "group",
      "name": "layout",
      "label": "Layout settings",
      "children": [
        {
          "type": "number",
          "name": "container_max_width",
          "label": "Container maximum width (px)",
          "default": 1200
        },
        {
          "type": "number",
          "name": "section_padding_v",
          "label": "Section top and bottom margins (px)",
          "default": 80
        },
        {
          "type": "number",
          "name": "border_radius",
          "label": "Rounded corners (px)",
          "default": 8
        }
      ]
    }
  ]
}

Expand theme.json values ​​as CSS variables

theme.json The values ​​defined in are expanded as CSS variables using HubL. All templates <head> Define it within or at the beginning of your global CSS.

/* Expand theme.json values as CSS variables
   Access with HubL's theme variable */
:root {
  /* ===== Color ===== */
  --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 }};

  /* ===== Typography ===== */
  --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 }};

  /* ===== Layout ===== */
  --container-max   : {{ theme.layout.container_max_width }}px;
  --section-padding : {{ theme.layout.section_padding_v }}px;
  --border-radius   : {{ theme.layout.border_radius }}px;

  /* ===== Breakpoint (fixed value/CSS variable cannot be used in a media query, so for reference only) ===== */
  --bp-sm  : 480px;
  --bp-md  : 768px;
  --bp-lg  : 1024px;
  --bp-xl  : 1280px;
}

Global CSS design (ITCSS approach)

In code base analysis of actual projects, global CSS is close to ITCSS (Inverted Triangle CSS). It was confirmed that it was designed with a layered structure. ITCSS isDefine CSS in the order of "abstract → concrete" and "wide range → local"With design philosophy, Prevents style override issues and level of detail conflicts.

ITCSS layer structure

/* ===== Objects: Layout pattern =====
   It does not have a design (color/font). Define only the structure.
===================================================== */

/* container */
.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 */
.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 */
.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); }
}

Upload your first theme

Once you're set up, upload your theme to HubSpot and see it working. Follow the steps below to complete the process from initial upload to confirmation.

# ===== First time: Upload all files =====
$ hs upload src/my-theme @my-theme --portal=dev
Uploading "src/my-theme" to "@my-theme" on portal "dev"...
✔ Done! Uploaded 12 files.

# ===== Under development: Automatic synchronization in watch mode =====
$ hs watch src/my-theme @my-theme --portal=dev
Watcher started, watching "src/my-theme"
# Automatically uploads every time you save a file

# ===== Confirmation after upload =====
# HubSpot admin → Marketing → Design Manager
# Success if @my-theme is displayed in the left pane

# ===== Apply template to page and check =====
# Website page → Create new page
# → Select "page.html" as template
# → Check the display in preview

{
  "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 or higher (Node 20 required)
  }
}

Chapter 1 Summary