Main Jobs

• Uploads your generated catalog.json file to Cloudflare R2.
• Clears/revalidates the CMS cache so it starts using the new catalog.

Catalog Update Flow

This flow ensures the generated catalog is validated, published, and then picked up by the CMS after cache invalidation.

Commands you can use :

pnpm publish:catalog
pnpm publish:catalog -- --skip-revalidate

Source and Destination

The script reads the generated catalog from:

scripts/catalog-json-generator/catalog.json

It publishes the file to R2 under:

catalog/catalog.json

With an artifact origin configured, the resulting public location is similar to:

{ARTIFACTS_ORIGIN}/catalog/catalog.json

Validation Before Publishing

Before uploading, the script performs a few basic checks:

• The catalog file exists.
• The file contains valid JSON.
• The root value is an object.
• A packages array exists.
• The packages array is not empty.

If any of these checks fail, publishing stops.

This prevents an invalid or empty catalog from replacing the currently published version.

Publishing to Cloudflare R2

The script connects to Cloudflare R2 using the configured R2 credentials and uploads the catalog to the configured artifacts bucket.

R2 acts as the central storage location from which the CMS can retrieve the runtime catalog.

The uploaded file is served as JSON and is configured with a short cache lifetime.

CMS Revalidation

After the upload succeeds, the script calls the CMS revalidation API:

POST /api/v2/revalidate

with the catalog scope:

{
  "scope": "catalog"
}

The request is protected using the shared revalidation secret.

The purpose of this call is to tell the CMS:

The runtime catalog has changed. Stop using the previously cached version.

The CMS can then fetch and use the newly published catalog.

Environment Configuration

The script depends on values from the artifacts environment configuration.

The main configuration groups are:

R2 Configuration

Used to upload the catalog:

ARTIFACTS_R2_ACCOUNT_ID
ARTIFACTS_R2_ACCESS_KEY_ID
ARTIFACTS_R2_SECRET_ACCESS_KEY
ARTIFACTS_R2_BUCKET
ARTIFACTS_ORIGIN

CMS Configuration

Used to refresh the CMS catalog cache:

CMS_ORIGIN
UI_BUILDER_REVALIDATE_SECRET

Normal Publishing

The standard command is:

pnpm publish:catalog

This performs the complete flow:

Validate
→ Upload to R2
→ Revalidate CMS

Publishing Without CMS Revalidation

The CMS refresh step can be skipped with:

pnpm publish:catalog -- --skip-revalidate

This performs only:

Validate
→ Upload to R2

This can be useful when the CMS is unavailable or when only the artifact needs to be published.

Failure Behaviour

The script stops and returns an error if an important step fails, including:

• Missing or invalid catalog file
• Missing R2 configuration
• Failed R2 upload
• Missing CMS configuration
• Failed CMS revalidation

This makes the command suitable for local development as well as automated deployment or CI workflows.

Summary

The script can be thought of as the publishing bridge between the generated runtime catalog and the CMS:

Local Catalog
     ↓
Cloudflare R2
     ↓
CMS Cache Refresh
     ↓
Latest Runtime Catalog Available

Its main responsibility is to ensure that when the catalog changes, the new version is both published and recognized by the CMS.