Skip to main content
Last modified: August 22, 2025
To validate and prevent unexpected production behavior, HuSpot will automatically run a series of health checks at the end of a build for a CMS React project. These health checks are enabled but will not fail a build by default. Build health checks look for the following:
  • For every React module, HubSpot verifies that:
    • The built module code can be imported.
    • There is a Component named export and that it is a React component (a function).
    • There is a fields named export and that it is a React element (<ModuleFields>...</ModuleFields>) or an array.
    • There is a meta named export and it is a JavaScript object.
  • For any island import (?island), client import (?client) or dynamic import (import(...)) linked from a React module’s code, the code must be able to be imported.
Failed health checks are logged in the build output only when strict health checks are enabled.

​
ESM and Common JS

In addition to verifying React modules, health checks will also uncover problematic ESM and Common JS issues before any code is deployed. HubSpot’s CMS React system is built on top of Vite, which can lead to complications when depending on other package that have misconfigured ESM exports. Relatedly, some packages that advertise CJS exports (i.e., package.json export / type) may actually include ESM import and export syntax (e.g., @mui/material@5.15.10). This can lead to situations where Vite’s compiler outputs an import to that package’s file in a node/modules..., which results in a runtime syntax error when the code is run. However, with build health checks, HubSpot can ensure that the problem is discovered at build-time rather than by visitors at runtime.

​
Build health check configuration

To explicitly configure your project’s build health checks, you can update the cms-assets.json file. 
{
  "label": "My CMS project",
  "buildConfig": {
    "healthchecks": {
      "enabled": true,
      "strict": true
    }
  }
};