Getting started

In this guide, you will build a “quality gate” for your content. You’ll learn how to use validateItems to check a page payload saved by your CMS, identify any items that your renderer cannot draw, and fail the process before a broken page ever reaches production.

Prerequisites

To follow this guide, ensure you have the following:

• Node 20 or newer.
• An ESM environment: We use a .mts file in the example, which Node and tsx load as an ES module. (Note: CommonJS files calling require('@evanion/widget') require Node 20.19 or 22.12+).
• tsx: A tool to run TypeScript files without a build step. You can run it via npx tsx.

The @evanion/widget package has no dependencies. If you are already using @evanion/react-widget or @evanion/astro-widget, you can import validateItems directly from the renderer instead of installing the core separately.

Install the widget core

Run the command for your preferred package manager:

npm install @evanion/widget

Create a Validation Gate

validateItems is designed to handle raw data. It types its first argument as unknown, meaning it can take a payload straight from JSON.parse without needing any type casting.

To create a check, you’ll need to define the “known types”—the list of widget types your frontend actually knows how to render. Save the following as check.mts:

/// <reference types="node" />
import { validateItems } from '@evanion/widget';
 
// The listing page as the CMS saved it, after an editor renamed the shelf's type.
const saved: unknown = JSON.parse(`[
  { "id": "brass-birmingham", "type": "listing", "props": { "title": "Brass: Birmingham" } },
  { "id": "tonight", "type": "featured-shelf", "props": { "heading": "On the table tonight" } }
]`);
 
// The widget types the shop's renderer has a component for.
const known = ['listing', 'shelf'];
 
const report = validateItems(saved, known).map(
  (problem) => `${problem.id} (${problem.type}): ${problem.message}`,
);
 
report; // -> ['tonight (featured-shelf): unknown widget type']
 
for (const line of report) console.error(line);
if (report.length > 0) process.exitCode = 1;
 
process.exitCode; // -> 1

How the Gate Works:

1. Parse the payload: It takes the JSON saved by the CMS.
2. Define the supported types: It lists the types your renderer supports.
3. Run the check: validateItems returns an array of problems.
4. Handle the result: If any problems are found, the script prints them and sets the exit code to 1, signaling a failure to your CI/CD pipeline.

In the example above, the shelf tonight uses the type featured-shelf, which is not in our known list. Because a renderer would simply skip this item, the page would lose its “On the table tonight” section. The script catches this and fails the run.

Run the Check from Your Terminal

You can execute your validation script using tsx:

npx tsx check.mts; echo "exit $?"

The terminal will print tonight (featured-shelf): unknown widget type and return exit 1. If you change featured-shelf back to shelf in the payload, the script will return exit 0.

Integrating the Gate into Your Workflow

This simple check can be integrated into several parts of your workflow to prevent broken content from reaching users:

• CMS Webhooks: Run the check in the handler that receives the “save” event from your CMS.
• CI/CD Pipelines: Validate all JSON payloads committed to your repository before deployment.
• Build Scripts: Run the check as a pre-processing step before the build generates the final pages.
• Test Suites: Run the check against your content fixtures to ensure they remain renderable.

Understanding the Reports

Your script now catches missing types, but that is only one of nine possible faults. What it reports shows how validateItems handles more complex issues, including nested item faults, and lists every possible error message.