Chapter 07

Scaffold

You will not start from a blank file. One command builds the skeleton of a component, with the boring plumbing already in place. Your job is to fill in the parts that are yours.

Updated 5 Nov 2026Pega 24 – 26

Words you will meet

npm run create
config.json

On this page6

01Why scaffold?
02Run the wizard
03Eight files, one by one
04config.json, line by line
05Every attribute, in one list
06config.json, trimmed to our button

The idea

Start from a skeleton.

Think of a form letter with the address and date already typed. A scaffold is the same: the builder asks six questions, then writes the files every component needs, wired together and ready to run. Without it you would have to know all of that plumbing before writing a single line of your own.

Play

Run the wizard.

Below is the real set of questions npm run create asks, with its real error messages. Click through the choices, and try a bad name to see it push back.

npm run createTry it: answer all six questions

terminal

$ npm run create

? Enter type of component

What it is asking

Which kind of part are you building? A button is a Field.

Try a bad answer for the name, like my button, to see the real error message.

Explore

Eight files, one by one.

The wizard writes a new folder under src/components/. Click each file to see its job.

What the scaffold wroteTry it: open each file in turn

The identity card · You edit this

config.json

A trimmed example

{  "name": "Acme_UI_StarRating",  "type": "Field",  "subtype": "Text",  "properties": [    { "name": "label", "format": "TEXT" }  ]}

Read by Pega when you publish, and by the builder when you build.
Decides what the component is and which settings a designer sees in the panel.
The next section walks through every line.

Only two of these hold your own thinking: config.json (what the component is) and index.tsx (what it does). The rest are support: looks, practice data, a showroom page, tests, and types.

The main file

config.json, line by line.

This is the file Pega reads. It is plain JSON. Click through the ideas in order: who it is, where it belongs, what kind it is, one setting in full, the controls you can choose, slots, show-when rules, groups and starting values. Every attribute name here is one found in a real library of components.

Anatomy of config.jsonTry it: click each idea

config.json (the highlighted part)

  "name": "Org_Lib_Accordion",  "label": "Accordion",  "description": "Sections that fold open and closed",  "author": "Your Name",

name is the code name. label is what a designer sees in the component picker. description is the hint under it. author records who wrote it. The name must be exactly three parts joined by underscores, letters and digits only (the validator checks the pattern ^[A-Za-z0-9]+_[A-Za-z0-9]+_[A-Za-z0-9]+$).

After editing, check the file with npm run validate-schema.

Reference

Every attribute, in one list.

The same names as a lookup table. The counts come from scanning 27 real components and the builder checker.

config.json attributesTry it: switch between the three levels

name: Code name, three parts joined by underscores.; all 27
label: Friendly name in the component picker.; all 27
description: One-line hint.; all 27
organization: First part of the key.; all 27
library: Second part of the key.; all 27
componentKey: Unique key Pega stores it under.; all 27
version: Semantic version, such as 1.0.0.; 26 of 27
author: Who wrote it.; all 27
type: Field, Template, Widget or Presentation.; all 27
subtype: The flavour, such as Text, FORM or PAGE.; all 27
subtypeLabel: Display name of the subtype.; 22 of 27
icon: Picture shown beside the component.; all 27
properties: The list of settings a designer can change.; all 27
defaultConfig: Starting values for those settings.; all 27

The identity card

config.json, trimmed to our button.

The scaffold writes a settings file with the generic properties of a Text field. We trim it to what our button needs: four settings. Read it top to bottom: who it is, what kind it is, and what a designer can change.

config.json

{  "name": "Acme_UI_CelebrateButton",  "label": "Celebrate button",  "description": "A button that celebrates when clicked",  "organization": "Acme",  "version": "1.0.0",  "library": "UI",  "componentKey": "Acme_UI_CelebrateButton",  "type": "Field",  "subtype": "Text",  "subtypeLabel": "Text",  "properties": [    { "name": "buttonText",      "label": "Button text",          "format": "TEXT" },    { "name": "celebrationText", "label": "Celebration message",  "format": "TEXT" },    { "name": "visibility",      "label": "Visible",              "format": "VISIBILITY" },    { "name": "disabled",        "label": "Disabled",             "format": "DISABLED" }  ]}

Each entry in properties becomes a control in Pega's settings panel. The format picks the control: TEXT a text box, VISIBILITY and DISABLED the standard show/hide and enable/disable pair. Other formats you will see in real projects include BOOLEAN, SELECT, NUMBER and PROPERTY.

Whenever you edit this file, check it before going further with npm run validate-schema.

Your turn

Questions and comments

Stuck on something, or have a thought? Write it here. To talk about one part, use the Comment button under that section's heading.