hubspot/cms-react

A repo to expose CMS react examples, React defaults modules, and more to CMS devs

HubSpot CMS React

Documentation

Check out an expanded documentation page at https://github.hubspot.com/cms-react/

Welcome!

Thank you for taking the time to learn about HubSpot CMS React. As always our goal is to solve for our customers so we welcome any and all feedback. Chat away in #cms-react with other HubSpot developers who are pushing forward with developing with React on the Hubspot CMS. If you do not have access to the developer slack, you can request access here.

How do React modules on the CMS work?

CMS React Modules and Partials are building blocks you can use to write React and JavaScript instead of HubL inside the HubSpot CMS. Note this doesn’t mean you will switch entirely away from HubL, rather we want to provide a pathway to begin writing React to render on both on the server and client. JS modules and partials are built from React components and can directly be referenced via HubL tags in your templates.

Can I use React modules on my CMS account?

Yes! Working with React modules is generally available and can be used with all tiers of the CMS, including free.

Default React modules

This directory contains a copy of all of our internal default React modules. As React modules do not appear in the Design manager, we made them available within this public repository so you can make your own copy and edit as you like. The modules you find in this directory are synced up with our internal code to ensure we keep them up to date.

What if I don't see a default React module in this repo but that is available for use within Hubspot?

Some default React modules contain code that is internal to Hubspot and thus cannot be used in a general way by external developers. If you are are seeking to utilize one of these modules, or otherwise get a better sense of how it works, please reach out to a developer advocate for more information.

React module boilerplate

If you'd like to get started with your own React module or one of our defaults, we have provided a boilerplate project for you to pick up and get started right away. This boilerplate comes complete with a Sample module so you can test working with this repo with only a few steps on your part. In order to get working with this boilerplate you simply have to:

• Become familiar with working with our CLI, if you are not already, with our Hubspot CLI documentation
• Run hs init and select your portal.
• Within the react-module-boilerplate/src run yarn deploy or npm deploy, which is a helper script we offer which runs the hs project upload react-module-boilerplate CLI command.
• You will be prompted to create this project in your portal. Confirm and the project will be created.
• Wait a few moments for the deploy to finish. You can view the projects within your portal at https://app.hubspot.com/developer-projects/{YOUR_PORTAL_ID}

Once the module is uploaded you should be able to see it when you go to edit a page, adding it like any other module.

Examples

In this repository is example usage of some of key features of React modules. These examples are are best understood alongside our official docs. You can quickly try things out without any local setup by opening this repo in Codesandbox.io.

Getting Started

The "Getting Started" example is the most up to date example of CMS React basics. It illustrates the definition and development of Modules with React, uses 3rd party dependencies, islands, and CSS Modules.

Hello World

NOTE: this is an older example, and Getting Started is a better first example

The "Hello World" example combines partials, modules, islands and CSS modules for styling to show a more cohesive yet straightforward example of how CMS React components and APIs work together.

Styling

In this example, we take a look at three different approaches to styling React components. This is not an exhaustive list and there are many ways that styles can be organized and implemented.

Islands

Islands are a key concept for React modules in HubSpot. In addition to stitching server-rendered React components into the HTML generated by HubL, JS modules and partials support client-side interactivity with islands. Similar to the islands concept from Astro, Fresh, and others, you can add an <Island /> inside your JS module or partial to automatically code-split and render a component on both the server and client. In addition to allowing you to reuse JavaScript code between the server and browser, islands help you write performant websites by giving you precise control over what JavaScript is shipped to the browser and when it runs.

Graphql + Storybook

GraphQL is the future for querying HubSpot data in your CMS pages. As part of JS Modules, a developer can export a GraphQL query string and the Module's root component will then be passed the query result. Additionally we show how a Module that uses GraphQL can be developed using our Storybook integration. This integration will automatically understand the field types of a module and generate controls for a Storybook story.

Todo MVC

It seems with every new FE technology on the web comes an implemetation of TodoMVC. We didn't want to be left out and ported a recent version that made use of React and React hooks to work as a JS Module with Islands. Additionally there is an example of our sharedIslandReducer which provides a redux like interface for sharing state across islands.

cms-react's Issues

Using RichText Component in React Module causing Content Editor to crash

Hi! Whenever I want to add or edit content inside a module which uses the RichtText component it's causing a crash inside the editor

[ERROR] Couldn't find module in widgetInRichText slice(anonymous) @ app.js:1
[ERROR] Couldn't find module in widgetInRichText slice @project.js:1

Is this a known issue? For now it's not useable and will use dangerouslysetinnerhtml

Failed to get dynamic context within GraphQL query

I cant seem to get this code working when using dynamic context with GraphQL:

export const query =`
# $product_uid: "foo"
query MyQuery($product_uid: String!) {
  HUBDB {
    my_product_collection(limit: 3, filter: {product_uid__contains: $product_uid}) {
      items {
        product_name
      }
    }
  }
}`

I got this error:

Variable 'product_uid' has coerced Null value for NonNull type 'String!

Tested with:

• @hubspot/cms-components: 0.14.16
• @hubspot/cms-dev-server: 0.14.13

Certain uses of Islands cause your website to disappear

As first mentioned in the Slack channel, depending on how you import/export an Island-ized component, your build will complete successfully but will result in an absurdly broken website.

components/basic/

  C.tsx

  D.tsx // imports C directly

components/modules/

  A.tsx // imports D as an island

  B.tsx // imports C directly

Result:

Hubspot CMS Dev Server doesn't generate types

There's a bug on hubspot-cms-dev server that cause hs-cms-dev-server --generateFieldTypes to not generate field types automatically.
the slashes are different on projectRoot and id in getEntryPathFromId function

Currently to (temporarily) fix it I have to change the isInModulesFolder function on

var isInModulesFolder = (filePath, _projectRoot) => {
    const projectRoot = path8.normalize(_projectRoot);
  const getEntryPathFromId = (id) => {
    return id.startsWith(projectRoot) ? id.replace(path8.normalize(`${projectRoot}/`), "") : "";
  };
  const currentModuleId = path8.normalize(filePath);
  const moduleEntryPath = getEntryPathFromId(currentModuleId);
  const subFolderTokens = moduleEntryPath.split(path8.sep);
  return {
    inModuleFolder: subFolderTokens[0] === "components" && subFolderTokens[1] === "modules",
    isRootModuleFile: subFolderTokens.length === 3
  };
};

Missing postinstall command on graphql-storybook example

running npm run start in examples/graphql-storybook doesn't work on because npm install does not have a postinstall command like the other example projects

Slack organization linked in the README is invite only

The link for the slack community in the welcome section seems to be invite only, but I see no way of creating an account unless you have an email in the list and there doesn't seem to be a way to request an invite.

Please advise :)

Input validation on modules

Im currently trying to implement an email input field with validation using react-hook-forms which will eventually trigger a custom API. However, whenever I go to submit the form, I get an error form within cms-dev-server saying "Failed to validate module fields". I've been unable to find anything in particular about inputs in modules. Is there something Im missing when it comes to implementation?

Hubspot CMS dev server not working

I'm was able to run npm run start with no error but when trying to access http://hslocal.net:3000 I hit an error: Invalid Host Header.

Repeated Field Groups

I checked the docs: https://github.hubspot.com/cms-react/field-types - doesn't seem to be support for repeated field groups to create react modules where an end user inside Hubspot CMS can add or remove repeated fields from a list.

Is this possible with React Modules?

One Island's throw seems to prevent subsequent Islands from hydrating

We've got three islands on this page. One of them (Breadcrumbs) threw an error, and the other one (Arc) never seemed to hydrate as a result.

We aren't 100% sure this is the case, but fixing Breadcrumbs also fixed Arc:

404 Path - HubdbRowFieldType and HubdbTableFieldType

I'm getting some 404 errors when I tried to access the following links:

• https://github.hubspot.com/cms-react/field-types/type-aliases/type-alias.HubDbTableFieldType.html
• https://github.hubspot.com/cms-react/field-types/type-aliases/type-alias.HubDbRowFieldType.html