@resultify/hubspot-cms-lib

Library with additional functionality on top of native HubSpot CMS CLI library (cli-lib) with command-line interface.

❗It should be used instead of hubspot-cli❗

Code Documentation

Table of contents

• Why?
• What's inside
• Install
• Usage
• Custom multi-account authentication
• Configuration
• Changelog

Why?

• The HubSpot CLI is a useful tool for connecting local development tools with HubSpot. However, integrating it smoothly into the development process can be a challenge, as there is no easy way to consolidate all local development tasks into one tool. To simplify the process and have one tool to manage all local development tasks, we created our own library that utilizes HubSpot CLI LIB and allows for seamless integration with other tools.
• For example, to compile SCSS files and upload them using the hubspot-cli Watch process, you typically need multiple tools or steps. This includes some task manager that can compile SCSS, copy CSS, and run a Watch process, as well as the hubspot-cli Watch/Upload process to upload the compiled files. However, with @resultify/hubspot-cms-lib, you only need one step. The Watch process combines SCSS, PostCSS, and Rolup.js compilers with the Hubspot Watch and Upload process, allowing you to accomplish everything with just one CLI command: npm run watch.
• Additionally, this library provides a very simple and straightforward way to authenticate multiple HubSpot accounts.

What's inside:

• Commands

  • build - compile all vendor files (scss, js, css)
  • watch - tracks file changes, compiles, and uploads/moves/deletes them to HubSpot
  • fetch - fetches all files from HubSpot
  • fetchModules - fetches all modules from HubSpot theme
  • upload - uploads all files to HubSpot
  • validate - HubSpot Marketplace validation
  • lighthouse - HubSpot Lighthouse validation
  • fields - converts theme/modules fields.js to fields.json
  • fetchDb - fetches chosen HubDB tables to local .json files
  • uploadDb - uploads and publish chosen HubDB tables from local .json files

• Compilers:

  • SCSS - SASS
  • JS - RollupJs
  • CSS - PostCSS

• Other features:

  • Custom multi-account authentication
  • FieldsJs
  • Watch process combines SCSS, PostCSS, and Rolup.js compilers with the Hubspot watch and Upload process.

Instal

This library should be a part of HubSpot Theme as an NPM dependency

npm i @resultify/hubspot-cms-lib

Usage

1. Add needed scripts to package.json

  "scripts": {
    "build": "cmslib --build",
    "watch": "cmslib --watch'",
    "fetch": "cmslib --fetch",
    "fetchModules": "cmslib --fetchModules",
    "upload": "cmslib --upload",
    "validate": "cmslib --validate",
    "lighthouse": "cmslib --lighthouse",
    "fields": "cmslib --fields",
    "fetchDb": "cmslib --fetchDb",
    "uploadDb": "cmslib --uploadDb"
  }

2. Add cmslib configuration to package.json

  "cmslib": {
    "themeFolder": "theme",
    "hubdbFolder": "hubdb",
    "vendorSrc": "vendor",
    "vendorDest": "theme/vendor",
    "lighthouse": {
      "performance": 75,
      "accessibility": 90,
      "bestPractices": 90,
      "seo": 80
    },
    "js": {
      "external": ["@popperjs/core"],
      "replace": {},
      "globals": {
        "@popperjs/core": "Popper = () => {}"
      }
    }
  }

3. Add .env file with multi-account authentication configuration
4. Run commands from package.json

npm run fetch
or
npm run watch

package.json example: https://github.com/Resultify/nimbly-lite/blob/master/package.json

More examples of how to run commands in your project

Custom multi-account authentication

1. Add .env file to your theme
2. Add a name of your Hubspot portal prefixed by hub_ with associated personal access key to it

.env file example

hub_sandbox=personal-access-key-for-this-sandbox-portal
hub_portalname=personal-access-key-for-this-portalname
hub_portalname2=personal-access-key-for-this-portalname2

Configuration

Add hubspot-cms-lib configuration object to package.json with needed options.

"cmslib": {
    "themeFolder": "theme",
    "hubdbFolder": "hubdb"
}

Options

|Option|Default value|Type|Description| |---|---|---|---| |themeFoldere|'theme'|string|HubSpot CMS theme folder name inside your repository| |hubdbFolder|'hubdb'|string| HubDB folder name inside your repository to store HubDB tables| |vendorSrc|'vendor'|string|Entry point folder name for third party libraries [e.g., vendor/css,vendor/js,vendor/scss]| |vendorDest|'theme/vendor'|string|Folder name for compiled third party libraries| |lighthouse||Object|lighthouse threshold numbers| |lighthouse.performance|75|number|| |lighthouse.accessibility|90|number|| |lighthouse.bestPractices|80|number|| |lighthouse.seo|80|number|| |js|[optional]|Object|rollupjs configurations| |js.external||Array|https://rollupjs.org/configuration-options/#external| |js.replace||Object<string, string>|https://github.com/rollup/plugins/tree/master/packages/replace| |js.globals||Object<string, string>|https://rollupjs.org/configuration-options/#output-globals|