Learn about the structure of a standalone Constellation DX component, and how to modify it to match your specific business need.

Updating the component definition

When you create a component, the Constellation DX Component Builder generates a config.json file, or component definition file. Every Constellation DX component created with Constellation DX Component Builder requires a component definition file to publish the component to Pega Platform™.

The component definition drives the UI authoring experience when you configure the component for use in Pega Platform, meaning that the property pane of the component in Pega Platform is defined by this file.

The UI view authoring relies on the information in the component definition to provide a streamlined experience when you edit the view metadata that is consumed at run time.

The component definition consists of header attributes and an array of property definitions. You can modify these attributes and add other attributes when you design your component.


A screen shot of the component definition file and its mapping to the respective properties in the property panel.

Component definition mapping to property panel

This is an evolving schema that is expanding with each release. For more information on the component definition, see Component definition.

The headers of the component definition file will be generated during component creation, along with sample properties relating to the component type and sub-type selected. Update the properties section of the component definition file to ensure that the App Studio author configuring your component has the best possible authoring experience. This is especially important if you are building a library of reusable Constellation DX components that may need to be configured for use across different business domains or different data model contexts.

Execution contexts of your component
There are two types of component run-time modes:
  • UI Authoring Preview mode
  • Portal run-time mode
UI Authoring Preview mode
When using UI Authoring in App Studio, your component will be executed by the UI Authoring Preview if you are previewing as Constellation. However, if you are previewing as DX API, your component will not be executed.

A screen shot of the Preview as Constellation window in UI Authoring in App Studio.

Preview as Constellation window
Your component is passed mock data from the UI Authoring preview component and this data might not be in an expected format. To prevent your Constellation DX component from displaying an error during preview, ensure that your component handles unexpected data being passed in to standard props as well as mock results returned from the PCore data APIs.
If you need to verify whether the component is being rendered in Authoring mode, you can check for the existence of a redux container called root/authoring-preview using the following PCore API: PCore.getContainerUtils().areContainerItemsPresent('root/authoring-preview')
This API will return true if the UI Authoring preview is displayed, and false if the UI Authoring preview is not displayed. Please note that the API also returns false if the Preview as DX API option is selected in UI Authoring.
Ensure that your component is rendered without any errors in both contexts. Test the component in the UI Authoring preview mode to ensure that it does not display any rendering errors.

Understanding your code

All Constellation DX components are functional React components with hooks that accept a set of props defined in the component props interface.

The current version of React used in Pega Platform 24.x is 17.0.2. However, it is expected to be updated to 18.0.2 in future major releases of Pega Platform. Constellation DX components are specifically designed to be used within the Constellation front-end architecture, which is a React single-page application. Please note that components created with other React frameworks and versions, including those that perform Server-side rendering (SSR), are not supported.

All Constellation DX components are created in the directory specified in the tasks.config.json file. Most Constellation DX component Builder projects typically use the default directory of src/components located in the Constellation DX component Builder project folder, which is created when you run the init command through npx.

All components have the following common characteristics:

Main React component code
The index.tsx file contains the entry point for the component and contains the majority of the component code.
Import declarations
  • This contains the React imports used by your component.
  • Several components are imported from the Constellation design system libraries. All Constellation DX components will have at least one import from the @pega/cosmos-react-core library. The version of the @pega/cosmos-react-core library and other Constellation design system libraries are predefined in your package.json file to align with the major version used by the Constellation front-end version that aligns with the version of Pega Platform you are using. You can use any components from the Constellation design system published on npm, but only a subset of these are documented with code examples on design.pega.com. Avoid changing these package.json versions as doing so may cause your component to stop rendering at runtime in a specific version of Pega Platform. For more information about the @pega/cosmos-react-core library, see @pega/cosmos-react-core.
  • The PConnFieldProps property contains a standard set of types of Constellation DX components.
  • A Styled Component wrapper component is automatically generated by Constellation DX Component Builder during component creation and added to your import declarations. A separate file is generated containing boilerplate code for styled components. For more information, see Styling a component using Styled Components.
Interface definition
This is the standard interface definition that describes the properties of your Constellation DX component. It extends the PConnFieldProps property, which defines a standard set of properties that are common to most Constellation DX components. The PConnFieldProps property is imported from the PConnProps.ts file, which defines the getPConnect API and imports the PConnect object from the @pega/pcore-pconnect-typedefs package that is automatically included in the package.json file of your project. For more information on the @pega/pcore-pconnect-typedefs package, see @pega/pcore-pconnect-typedefs.
NOTE: Do not modify the PConnProps.ts file, as it might be moved to a shared directory in the future, along with other common files.
The @pega/pcore-pconnect-typedefs package is the TypeScript type module that defines the types of the PCore and PConnect APIs. This package is directly referenced in the tsconfig.json file of the project and provides auto-complete and type-checking features for the PCore and PConnect APIs used in your project.
NOTE: The versions of the @pega/pcore-pconnect-typedefs package are aligned with the Pega Platform releases. Avoid modifying the version specified in the package.json file, as this may result in TypeScript generating type errors in the existing code and in any new components based on the Constellation DX component samples.
Component Render function
The component render function is the main body of the functional component.
All sample components need to be tested to ensure that their performance is acceptable for production. We create Effects to retrieve data using the PCore data APIs and also to subscribe and unsubscribe to the PCore PubSub and MessageServiceManager subsystems external to React. For more information about Effects, see You Might Not Need an Effect.
The component developer must perform most of the optimizations as the samples prioritize simplicity over performance.
The Constellation DX component is wrapped in a withConfiguration higher order component in the default export. This ensures that styles are properly scoped at run time for UI authoring preview and web embed.
Component definition
For a component to be published, it must have a valid config.json file that is validated against the component schema during the build and publication process. For more information on the component definition, see Updating the component definition.
Storybook
For more information on Storybook stories and the associated mock data, see Creating Storybook mocks for standalone Constellation DX components.
Migration of code to TypeScript
Over time, the samples of Constellation DX components have changed as Constellation DX Component Builder has transitioned to TypeScript and moved away from using PropTypes in the samples. Although TypeScript and PropTypes do not completely overlap, most React components do not use both. TypeScript is used for type-checking during development, while PropTypes can be used to enforce basic run-time type-checking of props passed into React components.
If you are migrating from an older version of Constellation DX Component Builder that uses PropTypes and JavaScript, consider migrating your components from PropTypes to TypeScript.

Styling a component using Styled Components

The Constellation design system uses styled components to encapsulate CSS styles for a Constellation DX component in a JavaScript object scoped to your component. This is commonly referred to as CSS-in-JS. For more information on styled components, see Styled Components.

While you will primarily use styles from the Constellation design system, you may need to create your own styled components for advanced component composition or when using a third-party library.
NOTE: Although styled components is the most popular CSS-in-JS solution in the React ecosystem, some third-party components may not offer integration with styled components. In this case, it is necessary to evaluate the use of third-party libraries based on their support for styled components. It is still possible to use third-party components that do not explicitly support styled components, but it is your responsibility to extract the CSS from a stylesheet and wrap it in a styled component, as well as to maintain alignment of these styles with changes in the third-party component.
The Constellation design system provides a wide range of design tokens in the Theme component. For more information, see Theme.

A screen shot of the theme properties used to apply design tokens to your styled components.

Theme properties

In the above figure, the highlighted base.palette['brand-primary'] design token points to the base.colors.blue.medium design token, which is set to the static RGB value #076bc9.

These tokens can be easily applied to your styled components using the theme object at run time, as shown in the figure below:

A screen shot of VS Code depicting the background color of the component uses the theme design token that represents the brand-primary color provided by the theme object: theme.base.palette['brand-primary'].

Token for styled components using theme object

In this example, the background color of the component uses the theme design token that represents the brand-primary color provided by the theme.base.palette['brand-primary'] design token.

Using Constellation design system's design tokens through the theme object ensures that your Constellation DX component will always reflect the portal theme applied in App Studio. This will result in a polished and integrated experience for end users and App Studio authors.


A screenshot depicting the Branding style that maps to the theme.base.palette['brand-primary'] design token.

Demo theme

In the above figure, we have changed the Branding style that maps to the theme.base.palette['brand-primary'] design token.

There may be instances where you need to override the applied out-of-the-box theme. In such cases, base your overrides on the original design tokens so that any changes to the token values will also be reflected in your overrides.

Any changes made in App Studio will reflect in the underlying Rule-UI-Theme instance and also for advanced theming you can edit the Rule-UI-Theme directly in DevStudio as long as you adhere to the Theme properties schema. For more information, see Theme properties.

The Constellation design system and Constellation front-end must have control over where styles are applied in portals and views. To ensure the integrity of Constellation design system styles, Constellation DX components have a special loader that prevents the styles in your component from impacting the global styles. To ensure that your Constellation DX component always previews well in UI Authoring and has your styles applied when being rendered through a Web Embed, use the Configuration component provided by the Constellation design system.

All Constellation DX component samples from Pega Platform 23.x onwards use the withConfiguration higher order component wrapper provided by the @pega/cosmos-react-core library. Therefore, you do not need to perform any additional actions as this wrapper ensures that the Configuration component is properly applied to your component at run time, and that your component styles will be applied in all execution contexts. For more information about the @pega/cosmos-react-core library, see @pega/cosmos-react-core.

To handle cases where you want to use the capabilities of the Configuration object directly, remove the withConfiguration wrapper in the default export, wrap your component render in a Configuration object, and set the required properties. For more information about the Configuration component, see Configuration.
NOTE: All examples of Constellation DX components are generated with a boilerplate styled components wrapper for you to add your styles. If you do not need to override any of the component styles that you are using, you can remove this from your code along with the associated imports and component reference from the render function.

Working with external libraries

When working with external libraries, check if they are compatible with React 17 and Styled Components v5.