Last modified: August 22, 2025
Typically, module and theme fields are configured in a fields.json
file. However, if you prefer to not use JSON, you can configure your fields with a JavaScript file instead. Writing fields with JavaScript enables you to abstract fields that you use often, dynamically generate new fields, and more easily update existing fields.
For example, when building a set of modules, you can abstract your module fields into partials which are then pulled into individual modules. By building modules that pull from one source of truth, you’ll no longer need to update those common fields in each module individually.
Below, learn how to write fields using JavaScript, including the necessary CLI commands, along with some examples to get you started.
Overview
At a high level, to write fields using JavaScript:- In the module folder or project root, include a JavaScript fields file instead of the
fields.json
file. You can use any of the following extensions:fields.js
fields.cjs
fields.mjs
(requires Node 13.2.0+ to be installed).
- Optionally, check your JavaScript before uploading to HubSpot by running
hs cms convert-fields
, which will save the output of the fields file locally asfields.output.json
. - Upload the asset to HubSpot through the CLI by running
hs upload
orhs watch
with a--convertFields
flag. On upload, HubSpot will convert the JavaScript file to afields.json
file.
Please note:When HubSpot converts the JavaScript file into the
fields.json
file, it does not store the original JavaScript file. To maintain a source of truth, it’s recommended to use a version control system like Git.Requirements
To use a JavaScript field file to generate fields:- The JavaScript fields file must be contained in a module folder or at the project root to be treated as the global
fields.json
file. - The module or theme must not also include a
fields.json
file. Including both will prompt you to select one or the other at upload. - The JavaScript fields file must export a function as its default export. The exported function can accept an array of strings called
fieldOptions
, and must return an array of objects. Each entry in the returned array must be one of the following:
- A JavaScript object with valid field key-value pairs.
- A JavaScript object with a
.toJSON()
method. When run, this method must return a value that meets criterion 1. - A
Promise
that resolves to a JavaScript object that meets criterion 1.
CLI commands
Use the following CLI commands when writing module fields with JavaScript.Check JavaScript file locally
Check your work locally by runninghs cms convert-fields
, which saves the output of your JavaScript fields file as fields.output.json
in the same directory as the JavaScript fields file.
hs cms convert-fields
accepts the following flags:
Flag | Description |
---|---|
--src | The location of the JavaScript fields file, or a directory. |
--fieldOptions=[options] | Accepts a space-separated list that will then be passed to every exported JavaScript fields function as an array before compile-time.For example, you can configure fields to have different labels depending on whether a --fieldOptions=qa flag is set.View an example of this below. |
Upload to HubSpot
Upload to HubSpot to begin the process of converting the JavaScript file to afields.json
file by running either hs upload
or hs watch
.
hs upload
and hs watch
accept the following flags:
Flag | Description |
---|---|
--convertFields | Enables JavaScript fields functionality. |
--saveOutput | Saves the JavaScript fields file output as fields.output.json in the same directory as the JavaScript fields file. If not included, HubSpot will save the output of the JavaScript fields file to a temporary directory then delete it after upload. |
--fieldOptions=[options] | Accepts a space-separated list that will then be passed to every exported JavaScript fields function as an array before compile-time.For example, you can configure fields to have different labels depending on whether a --fieldOptions=qa flag is set.View an example of this below. |
Examples
Below, review examples of using JavaScript to write fields files.Regular object
The followingfields.js
file writes a regular object:
Common fields
The followingfields.js
file creates a set of common fields to be used across multiple modules:
Change fields based on passed options
The followingfields.js
file changes the module’s fields based on whether the
--fieldOptions=[qa]
flag was included when running hs cms convert-fields
, hs upload
, or hs watch
:
Add JSON from other files
The followingfields.js
file includes styles from a styles.json
file:
Make async calls
The followingfields.js
file includes an asynchronous call by setting the exported function as async
. If you return a Promise, the CLI will wait for the Promise to resolve before writing the fields.json
file.
Use external field object libraries
The followingfields.js
file includes an external library. Libraries such as @iGoMoon/hubspot-fields-js are supported, as their fields objects expose a .toJSON()
function.