LearnConstellation.

Chapter 05

Your workshop

Nobody cooks in an empty room. Before the button, a few tools. Most of this is checking what you already have, and it takes ten minutes.

Pega 24 – 26

Words you will meet

  • Node.js
  • npm
  • Git

The idea

Your laptop becomes a small factory.

A custom component is built on your own computer, using free tools, and only at the very end sent to a Pega server. So the first job is making sure your laptop has the tools. Three of them do most of the work:

Node.jsA program that runs JavaScript outside the browser. Every build tool in this story runs on it. runs the tools. npmNode Package Manager. Downloads the libraries a project depends on and runs its shortcut commands. fetches the libraries and runs the project's commands. GitRecords every change to your files, so you can undo mistakes and share work with a team. keeps a history of your work.

Before anything

What you need, and why.

Seven things, explained from zero. Open each card for what it is, why this guide needs it, how to check you have it, and the mistake people make. Nothing is assumed.

PrerequisitesTry it: open each card
  • What it is
    A window where you type instructions instead of clicking. PowerShell or Git Bash on Windows, Terminal on macOS, any shell on Linux. VS Code has one built in.
    Why you need it
    Every build step in this guide is a command: install, create, preview, test, publish.
    How to check
    Open it and type: pwd (Git Bash, macOS, Linux) or Get-Location (PowerShell). A folder path comes back.
    Common trap
    Commands run in the folder the terminal is currently in. If something says "file not found", check you are inside the project folder first.

Start from zero

Install your toolkit.

Three free programs: Git (on Windows it includes Git Bash, a friendly terminal), Node.js and VS Code, the editor. Pick your system and follow along.

Toolkit installerTry it: pick your system, copy a command

0 of 3 installed

  1. Keeps a history of your files and fetches the team project. On Windows the installer also gives you Git Bash, a friendly terminal.

    Installwinget install --id Git.Git -e
    Checkgit --version

    Prefer an installer? Download from git-scm.com/install/windows ↗

    In the installer, accept the defaults. That includes Git Bash.

Then, in order
  • Open the project folder in VS Codecode .
  • Open its built-in terminalCtrl+` (backtick)
  • Install the project librariesnpm ci

Commands use each system's standard package manager (winget, Homebrew, apt). Close and reopen your terminal after installing so it can find the new tools.

Warm up

Practice the terminal.

A terminal is a text box where you type instructions. Nothing here can break anything, so try a few.

Practice terminalTry it: type node -v and press Enter
practice terminal (pretend)

Type a command, or press a button below.

Check

The tools, ticked off.

Open a terminal (PowerShell, Terminal, or the one inside your editor) and run each command. Tick the tool when you see the expected answer.

Workshop checklistTry it: run each command, then tick it off

0 of 5 ready

  • Node.js 24

    Runs the builder, Storybook and the tests. The repo pins it in a file called .nvmrc.

    $ node -v

    You should seev24 or newer (tested on 24.22.x for Pega 26.1; Node 20.x for Pega 24/25). Node 26 works after one sign-in fix: see Troubleshooting.

    nvm use # switches to the version in .nvmrc, if you use nvm or fnm

  • npm 10 or newer

    Downloads every library the project needs. It arrives with Node 24.

    $ npm -v

    You should see10.x or 11.x (tested on npm 11.19.x for Pega 26.1; npm 10.x for Pega 24/25)

  • Git 2.30 or newer

    Fetches the project and records your changes.

    $ git --version

    You should seegit version 2.30 or higher

  • A code editor

    VS Code is a good fit: the project ships shared editor settings for it. Optional.

    $ code --version

    You should seeany version prints a number (skip if you use another editor)

  • A Pega server and sign-in details

    You publish to a real server. Ask your Pega administrator for the server address and an OAuth client. The next chapter explains each value.

    You should seea server URL ending in /prweb/, a client ID and a client secret

Get going

Get the project, and install it.

Most teams keep all their components in one shared project (a Git repository). Ask for its address, then copy it to your machine and install what it needs:

Terminal
git clone <your-repository-url>cd <the-project-folder> nvm use     # optional: switch to the Node version in .nvmrcnpm ci      # install the exact versions listed in package-lock.json

npm ci is the careful cousin of npm install: it installs exactly what the project's lock file says and nothing newer, so everyone on the team gets identical tools. It may take a few minutes the first time.

One choice that matters

Match the builder to your Pega.

The builder is the tool that creates and publishes components, and it comes in one flavour per Pega release. The rule of thumb is simple: use the builder that matches the server you publish to.

Which tools do I need?Try it: pick your Pega version
My Pega server is…

Use these tools

Builder tag
release-26.1
Builder version
26.1.11
cosmos-react
9.29.0
typedefs
5.1.1

Publishing ruleThe ruleset version you publish to must already exist in your application.

Tool versions come from npm release tags; the ruleset rules come from the project's setup notes.

Orientation

The project, from the root.

After npm ci the project folder holds a lot of files. Most are plumbing. Pick a group to see what each file is and whether you should ever touch it.

Project tourTry it: pick a group, then a file

Tools ready, project installed. The next move is the one that trips most people up: telling your laptop how to reach the Pega server, and proving it is allowed to.

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.

3–20 letters, digits, _ or -. Kept in this browser so you are not asked again.

0/1000

A hands-on guide by Sanjeev Kujur. Independent, and not affiliated with or endorsed by Pegasystems.

Covering Pega Infinity versions 24.2, 25.1, and 26.1 · Updated 5 Nov 2026