January 21, 2022

Upgrading to Cosmos React, do it or not?

Pega is constantly evolving. As a Pega expert, you want to keep up, and take advantage of all the new features. Cosmos React is one such new technology, introduced in 2020 as the way forward. Meanwhile, Cosmos React is available as an early adopter, alongside Theme Cosmos and Theme UI-Kit. To explain why Cosmos React is currently still in the Early Adopter phase, we explain what Cosmos React is and what you can and cannot do with it. Upgrading to Cosmos React: to do or not to do?

Think of it as a hydrogen car. While the consensus is that a hydrogen car is the more sustainable and better solution in the long run; in practice, however, its development is still in its infancy. So should you go for it? Especially when you know that a good alternative, the electric car (Cosmos section-based UI) is now in full development and has already proven itself.

What is (Cosmos) React?

React is an open-source technique developed by Facebook to build web pages. It consists of a library of UI components and is a modern way to build responsive websites and apps.

It has long been possible to use Pega in combination with React, using the DX API: a set of messages that allow you to query data from Pega to display it in your UI. With Cosmos React, Pega is moving towards using this technique by default.

source: Pegasystems

Cosmos React is Pega’s solution for separating the front and back end of your application. Traditionally, the Pega server sends HTML to the user, and so Pega determines what the user sees, and how it is displayed. Cosmos React separates this: Pega still determines the content, but the UI, how it is displayed, is driven by React.

The fact that with Cosmos React you work with a set of fixed components immediately explains why the Cosmos design principles insist on using design templates. Only if you use a design template that corresponds to a React component will the React code know how to present the data from Pega. If you have built a custom screen without design templates, you will also need custom logic on the React side.

How complete is Cosmos React UI now compared to Cosmos Section-based UI?

To get right to the point, Pega says the following about it:

“Cosmos React uses the latest technology, but offers fewer functionalities compared to Theme Cosmos. Consequently, Cosmos React is best suited for early adopters who understand its narrower feature set and capabilities. As a best practice, use Theme Cosmos for complex applications and a mature, reliable architecture.”

So what are these differences in functionality offered? What ‘shortcomings’ should you take into account if you do decide to use Cosmos React UI? To point out the differences, Pega has created a nice overview. We have summarised this overview below in the main points to consider if you want to start using Cosmos React UI.

Development Recommendations for 8.6
Cosmos React UI Cosmos Section-based UI
Landing pages
 Out of the box widgets for worklist and Pulse Case lifecycle with stages and steps Open cases from Landing pages & other case references Client-side expressions and when rule-based expressions Column filtering, sorting and grouping Localization Web Mashup & Mobile Rule delegation Reports & report browser Paragraph rule Development Branching Generate PDF automations Attachment categories SecurityOAuth 2.0 authentication Atribute Based Access Control (ABAC) 

To already use Cosmos React despite its limitations, you can use ‘Hybrid-mode’. Hybrid-mode allows you to merge Cosmos React UI features with existing Cosmos Section-based UI. The advantage of this is that you can update to React UI incrementally, without losing existing functionality, while enjoying the new benefits of React UI (better performance and user experience).

For instance, Cosmos React UI provides improved performance during rendering, sorting, filtering and grouping of tables. In addition, the full case view in App studio will load and respond faster.

Read more technical information here:

The table above shows that a number of key features of Pega are already supported in Cosmos React UI. Examples include:

  • Landing Pages
  • Case lifecycle with stages and steps
  • Opening cases from Landing pages & other cases
  • OAuth 2.0 authentication

The above features are important for using Cosmos React UI in the Early Adopter phase. Without Case lifecycle management, being able to open cases or OAuth 2.0 authentication, it becomes impossible to start using Cosmos React UI at all for many practical situations.

However, it can also be seen that a number of features are not yet supported in Cosmos React UI. These points largely influence the decision whether or not to go for Cosmos React UI.
The lack of Localisation in React UI will not be an immediate problem for English-oriented applications, as the standard is English. However, for applications that need to be used in a language other than English, the lack of this functionality will cause problems. These applications are almost always Dutch-oriented. The workaround for this would be to build sections expressly in Dutch.

From a functional perspective, the lack of Reports and Attachment categories causes problems. This results in the fact that reports cannot (yet) be run and documents cannot be added by users in a well-ordered manner. In our view, this is a major roadblock to working with Cosmos React UI already, as such functionality is desired for almost every major application.

The lack of development branching needs some additional explanation. Building your data model, case structure and design templates still goes through branches in Pega. The actual implementation of the front-end will be outside Pega, but can just go there through a software lifecycle with branching. The issue Pega does not currently support is the interaction between the front-end implementation outside Pega and the code still under development within Pega. From a development perspective, this ensures that development will have to take place in phases. You will have to merge the code in the Pega branch before you can properly test the stand-alone front-end code. When you have a large application to maintain with a lot of concurrent development, the lack of a mature way of branch development currently makes it impossible to develop efficiently with Cosmos React UI in its current version.

The UI is generated by a React server: the Constellation service:

Here you can see what the constellation engine working method looks like.

The Constellation engine serves static building blocks, which populate in your browser with data from Pega. For example, the Constellation engine sends the component containing the case summary to your browser. Pega then provides the case data to populate that component. All data from Pega is via API messages. The Constellation engine uses React to build the web pages.

Making this separation has the advantage of removing dependencies. A front-end team can create new visual components without having to touch Pega’s content.

There are a number of conditions that must be met before Cosmos React UI or Hybrid mode can be used. For instance, it is necessary to have a secure HTTPS connection, a Constellation engine must be running and there is a difference between on-premises and Cloud applications. The table below provides a brief overview of the conditions that need to be met.

  Applicatie type
On-Premise Cloud
Constellation Engine Should be installed. OOTB present
Docker/ Kubernetes When not installed with Pega Infinity see:

Secure HTTPS protocol Required Required
DSS en REST API configuratie Required Happens automatically
App alias Required Required

Besides certain technical conditions, there are also conditions in your application structure that must be met. This is because Cosmos React UI does require the use of design templates. If you upgrade from Cosmos Section-based UI to Cosmos React, almost all sections will already have been created via design templates. Should you want to upgrade from the UI-Kit to Cosmos React, take into account a lot of preparation to convert your sections to design templates.

In addition, avoiding custom CSS in sections is a plus. Indeed, custom CSS in Pega can result in unpredictable UI behaviour if you simultaneously try to present your screens via Cosmos React UI.

So, according to Pega best practices, we recommend upgrading to React only if you are already using design templates and have not applied custom css logic in your application.

Our recommendation

The question is, what do you choose? Do you invest now in the more sustainable hydrogen car with teething problems (Cosmos React UI), do you go for the electric car that has already proven itself and is still developing, or do you go for the hybrid variant where you have the advantages of both worlds?

1. Assess your situation

Keep in mind that Cosmos React is still an early adopter at the moment and some features are not yet offered that Theme-Cosmos does. With that, Cosmos React may therefore still be a little too early for your case study. Currently, we would advise against going full Cosmos React for larger applications, use Hybrid Mode instead. If the limitations of Cosmos React are not an obstacle for your scenario, then by all means go ahead and experiment with it.

2. Move away from UI-Kit and use Cosmos

In any case, our advice would be to switch to that electric car as soon as possible. Pega Cosmos is UI/UX area the new standard and offers many advantages over the outdated UI-Kit. This will get you ready for a future move to Cosmos React.

3. Experiment with Hybrid mode

If you are already using Cosmos, experiment with Hybrid mode. In it, you run entirely on Cosmos, but no longer depend on UI-Kit for tables, for instance. You lean on the working Cosmos section-based UI and can use the certain benefits of Cosmos React UI.


Bram Agterberg

Pega Consultant

Tom Dekker

Pega Consultant


Are you curious what this development could mean for your company or Pega project? Contact us or Bram and Tom. We would be happy to think along with you.


Sign up for our monthly newsletter