@pega/constellation-corejs

The orchestration engine at the core of Pega's Constellation UI platform

One engine, every surface: the same PCore / PConnect contract runs unmodified from a bundler-built SPA, to a Node SSR shell, to a browser <script> embed.

@pega/constellation-corejs provides the PCore and PConnect APIs, which bridge Constellation's reactive data model, metadata resolution, rule orchestration, and event bus to any UI layer, including Pega's React/Cosmos design system and custom third-party implementations.

| Capability | Description | | --------------------------------- | --------------------------------------------------------------------------------------------------------------- | | Standards-based module resolution | Full Node.js exports map; no manual path configuration required | | Multiple distribution targets | Pre-built, minified ESM, browser IIFE, and bootstrap-shell bundles | | First-class TypeScript support | Declarations published through exports["types"]; no separate @types package | | Version parity with Infinity | Each npm release version corresponds exactly to the Pega Infinity release it ships with |

Table of contents

• Quick start
• Requirements
• Installation
• Module resolution
• Integration patterns
  • Bundler / Node ESM
  • Browser via Import Map
  • Browser <script> IIFE
• Distribution bundles
• Performance and delivery
• TypeScript support
• API reference
  • PCore
  • PConnect
  • Sub-APIs at a glance
• Reactive state model
• Building from source
• FAQ
• Security
• License

Quick start

npm install @pega/constellation-corejs

import PCore from '@pega/constellation-corejs';

PCore.onPCoreReady(() => {
  const env = PCore.getEnvironmentInfo();
  console.log(`Connected to the ${env.getApplicationLabel()} application`);
});

Module resolution, type declarations, and bootstrapping are handled automatically. See Installation for version-pinning guidance and Integration patterns for bundler-specific notes.

Requirements

| Requirement | Version | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | Node.js | 24 LTS (≥ 24.0.0) — for tooling, builds, and Node/SSR usage | | npm | ≥ 11 (ships with Node 24 LTS) | | TypeScript (optional) | ≥ 6.0.3 | | Runtime targets | Evergreen browsers with ES2024 support (Chrome/Edge 119+, Firefox 121+, Safari 17.4+), Node.js, and isomorphic/SSR environments |

[!TIP] Use fnm or nvm to pin your project to Node 24 LTS. An .nvmrc / .node-version file set to 24 is recommended.

⬆️ Back to top

Installation

npm install @pega/constellation-corejs

[!WARNING] Pin to the exact version that matches your Pega Infinity environment. Floating ranges across minor versions are not recommended because the Constellation data model evolves with each Infinity release.

// package.json — always pin exactly
"dependencies": {
  "@pega/constellation-corejs": "27.1.0"
}

⬆️ Back to top

Module resolution

The package ships a full exports map (package.json#exports). Bundlers and runtimes resolve the correct entry automatically — no path hacks or main-field fallbacks needed.

// Resolved automatically per environment:
{
  "exports": {
    ".": {
      "types": "./lib/index.d.ts", // TypeScript
      "import": "./dist/constellation-corejs.esm.js" // ESM — bundlers, Node ESM
    }
  }
}

sideEffects: true is declared so bundlers preserve the module-level bootstrapping code that initialises the engine's internal registry.

⬆️ Back to top

Integration patterns

Bundler / Node ESM

Works out of the box with Vite, webpack 5, Rollup, esbuild, and Turbopack. The public root entry provides the default PCore singleton and preserves its module-level initialization side effects.

import PCore from '@pega/constellation-corejs';

const env = PCore.getEnvironmentInfo();
console.log(env.getApplicationLabel(), env.getLocale());

Vite — no configuration required. The exports map is resolved natively.

webpack 5 — set resolve.conditionNames: ['import', 'module', 'require', 'default'] if you override the default condition list.

esbuild — pass --conditions=import when building for Node ESM or omit for the default browser condition.

Browser via Import Map

Import maps are baseline-available in all evergreen browsers since 2024 and are the modern, zero-bundler alternative to <script> tags.

<script type="importmap">
  {
    "imports": {
      "@pega/constellation-corejs": "/assets/constellation-corejs.esm.js"
    }
  }
</script>

<script type="module">
  import PCore from '@pega/constellation-corejs';

  PCore.onPCoreReady(() => {
    console.log('Engine initialised:', PCore.getEnvironmentInfo().getApplicationLabel());
  });
</script>

[!TIP] Pair with <link rel="modulepreload" href="/assets/constellation-corejs.esm.js"> to eliminate the round-trip penalty on first navigation.

Browser <script> IIFE

Use the self-contained IIFE bundle when a module system is unavailable (legacy micro-frontend shells, CMS embeds, Salesforce Lightning, etc.). The bundle exposes PCore on window.

<script src="/assets/constellation-corejs.global.js" defer></script>
<script>
  document.currentScript.ownerDocument.addEventListener('DOMContentLoaded', () => {
    PCore.onPCoreReady(() => {
      const env = PCore.getEnvironmentInfo();
      console.log(env.getApplicationLabel());
    });
  });
</script>

[!IMPORTANT] Generate a Subresource Integrity (SRI) hash at build time and add it to the <script> tag in production to prevent supply-chain tampering:

openssl dgst -sha384 -binary dist/constellation-corejs.global.js | openssl base64 -A

<script
  src="https://cdn.example.com/constellation-corejs.global.js"
  integrity="sha384-<hash>"
  crossorigin="anonymous"
  defer
></script>

⬆️ Back to top

Distribution bundles

All bundles live in dist/. Source maps are not included in the published bundles.

| Bundle | Format | Target | Primary use case | | ------------------------------------- | ------ | ------ | ------------------------------------- | | dist/constellation-corejs.esm.js | ESM | ES2024 | Bundlers, Node ESM/SSR, Import Maps | | dist/constellation-corejs.global.js | IIFE | ES2024 | Browser <script> tag, CDN | | dist/bootstrap-shell.js | ESM | ES2024 | Minimal loader / host-shell bootstrap |

Supported environments per bundle:

• constellation-corejs.esm.js — plain ESM, fully self-contained (no bare specifiers, no CommonJS/require, no AMD/UMD). Works unmodified as:
  • a dependency consumed by any modern bundler (webpack 5, Vite, Rollup, esbuild, Rspack)
  • a Node.js / SSR import (dynamic import() of a file path or URL)
  • Deno or Bun (both ESM-first, URL-import friendly)
  • a native browser ES module (<script type="module">, import maps)
  • an ESM Web Worker (new Worker(url, { type: 'module' }))
• constellation-corejs.global.js — IIFE, browser-only. Assumes a global scope (globalThis/window) for the wrapper and attaches the engine as globalThis.PCore; not usable in Node/SSR or workers. For plain <script> tags without any module system — legacy micro-frontend shells, CMS embeds, Salesforce Lightning.
• bootstrap-shell.js — browser-only, ESM. Fetched at runtime by the host page's own bootstrap logic (pega-bootstrap-component.js / pega-embed.js) to dynamically load the engine; its filename is kept as-is for legacy and backward compatibility with already-deployed hosts.

Not covered by these bundles (intentionally out of scope): CommonJS require() and AMD/UMD (RequireJS).

Configure your CDN / nginx / Caddy to compress these files (e.g. Brotli/gzip on the fly, or a build step of your own) before serving.

⬆️ Back to top

Performance and delivery

• HTTP/2 push / Early Hints (103): Emit an Early Hints response for constellation-corejs.global.js to eliminate round-trip latency on the critical render path.
• Modulepreload: When using the ESM bundle with an import map, add <link rel="modulepreload"> so the browser fetches and parses the module before it is needed.
• Cache-Control: The bundle filename is stable per Infinity version. Use an immutable, long-lived cache header (Cache-Control: public, max-age=31536000, immutable) and version-stamp the URL path on upgrade.

⬆️ Back to top

TypeScript support

TypeScript declarations are included and wired through the exports map — no separate @types/ package needed. This package requires TypeScript 6.0.3+ and supports moduleResolution: "bundler", node16, and nodenext.

// Named type imports — zero runtime cost
import type PCore from '@pega/constellation-corejs';
import type { PConnect } from '@pega/constellation-corejs';

Enable moduleResolution: "bundler" (or "node16" / "nodenext") in tsconfig.json to allow the TypeScript compiler to follow the exports map:

// tsconfig.json
{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler", // or "node16" / "nodenext"
    "strict": true
  }
}

⬆️ Back to top

API reference

Full API documentation is generated from TypeDoc and published with every release. The following is a technical orientation to the two primary surfaces.

PCore

PCore is a process-scoped singleton, initialized once by the engine bootstrap. It owns all platform-wide services that are context-independent: the Redux store, pub/sub event bus, constants registry, and environment metadata. Every PConnect instance is a lightweight, context-bound view onto this shared engine state.

// ── Environment ─────────────────────────────────────────────────────────────
const env = PCore.getEnvironmentInfo();
// env.getApplicationLabel(), env.getLocale(), env.getTimeZone(), …

// ── Constants ────────────────────────────────────────────────────────────────
const { CASE_INFO, DATA_INFO } = PCore.getConstants();

// ── Reactive store (Redux Toolkit) ───────────────────────────────────────────
const store = PCore.getStore();
store.dispatch(mySlice.actions.update(payload));
const state = store.getState();

// ── Pub/Sub event bus ────────────────────────────────────────────────────────
const pubSub = PCore.getPubSubUtils();
const subscriptionName = 'case-opened';
pubSub.subscribe('CASE_OPENED', (data) => handleCaseOpen(data), subscriptionName);
pubSub.unsubscribe('CASE_OPENED', subscriptionName);
pubSub.publish('CUSTOM_EVENT', { caseID: 'ACME-WORK-1001' });

// ── Namespace utilities ───────────────────────────────────────────────────────
const ns = PCore.getNameSpaceUtils();
const fqn = ns.getDefaultQualifiedName('myCustomRule'); // → "ACME-myCustomRule"

// ── Cascade / data page ───────────────────────────────────────────────────────
PCore.getDataPageUtils().getDataAsync('D_CaseList', 'app/primary', {}, { pageSize: 50 });

For the complete surface, see PUBLIC_API.md.

PConnect

PConnect is a context-bound bridge object returned by getPConnect() inside a component render cycle. Each instance is scoped to a single component node in the Constellation view tree, providing reactive access to that node's current value, metadata, and action dispatch.

// Obtain inside a component bridge function / hook
const pConn = getPConnect();

// ── Data access ───────────────────────────────────────────────────────────────
const status = pConn.getValue('pyStatusWork'); // current field value
const caseID = pConn.getValue('pxRefObjectKey'); // case reference

// ── Metadata ──────────────────────────────────────────────────────────────────
const meta = pConn.getFieldMetadata('pyStatusWork');
// meta.label, meta.required, meta.readOnly, meta.validationMessages, …

// ── Action dispatch ───────────────────────────────────────────────────────────
const actions = pConn.getActionsApi();
actions.triggerFieldChange('pyStatusWork', 'Resolved-Completed');
actions.openLocalAction('pyUpdateWorkflowStatus', { type: 'Case' });

// ── Container management ──────────────────────────────────────────────────────
const containers = pConn.getContainerManager();
containers.addContainerItem({ context: 'app/primary_1', semanticURL: 'RequestApprovals/REQ-1' });

// ── Cascade / dependent fields ────────────────────────────────────────────────
PCore.getCascadeManager().registerFields(
  'app/primary_1',
  'caseInfo.content',
  ['.pyStatusWork', '.pyUrgencyWork'],
  () => {},
  'case-status'
);

// ── Localisation ──────────────────────────────────────────────────────────────
const display = pConn.getLocalizedValue('Open'); // locale-aware label

Sub-APIs at a glance

For the complete surface, see PUBLIC_API.md.

| API | Obtained via | Responsibility | | ------------------ | ----------------------------- | ------------------------------------------------ | | ActionsApi | pConn.getActionsApi() | Field changes, local/flow actions, refresh | | ContainerManager | pConn.getContainerManager() | View-container lifecycle (add, remove, navigate) | | CascadeManager | PCore.getCascadeManager() | Cascading field dependency registration | | DataPageUtils | PCore.getDataPageUtils() | Async data-page fetches | | PubSubUtils | PCore.getPubSubUtils() | Platform-wide pub/sub event bus | | NameSpaceUtils | PCore.getNameSpaceUtils() | Rule and class FQN construction | | EnvironmentInfo | PCore.getEnvironmentInfo() | Application, locale, time zone, feature flags |

⬆️ Back to top

Reactive state model

The engine manages UI state through a Redux Toolkit store exposed via PCore.getStore(). Component bridges subscribe to state slices — Constellation's internal diffing ensures components re-render only when their relevant slice changes.

The pub/sub bus (PCore.getPubSubUtils()) complements the store for cross-cutting events (session expiry, case assignments, real-time WebSocket pushes) that do not map cleanly to a single store slice.

[!WARNING] Do not mutate store state directly. Always dispatch through PConnect action APIs or PCore.getStore().dispatch() with an official action creator. Direct mutation bypasses Constellation's change-detection pipeline.

⬆️ Back to top

Building from source

Library build — TypeScript → ESM

Compiles src/ to lib/ with full .d.ts declarations. The public package entry uses the self-contained bundle in dist/; the compatibility lib/* export preserves existing bundler-based integration imports.

npm run build

Produces:

lib/
  index.js        ← ESM implementation
  index.d.ts      ← TypeScript declarations

Deep imports under lib/* require a bundler. Direct Node ESM deep imports are not supported. Library modules are published as emitted by TypeScript, without import rewriting or an ESM package marker. The build adds small aliases for directory entrypoints so existing directory imports resolve through the wildcard export.

Distribution bundles — esbuild

Produces the standalone, browser-ready bundles under dist/. Uses esbuild for transpilation and minification (production builds).

# Production — minified
npm run build:dist

# Development — unminified (faster iteration)
npm run build:dist:dev

[!NOTE] The build pipeline (build-dist.mjs) runs esbuild with the es2024 target and minification enabled for production.

CI validates the package export targets separately after the build. To run the same check locally from the repository root:

npm --prefix packages/corejs run validate:exports

⬆️ Back to top

FAQ

See Distribution bundles for the full breakdown. As a rule of thumb: use constellation-corejs.esm.js for any bundler, Node, or import-map setup, and constellation-corejs.global.js only for plain <script> embeds without a module system.

Yes — the ESM bundle is a valid Node.js / SSR import. Code paths that touch browser-only globals still require those globals to exist or be polyfilled at runtime; see Distribution bundles for environment-specific notes.

Yes, via new Worker(url, { type: 'module' }) against the ESM bundle. See Distribution bundles.

No, both are intentionally out of scope. Only ESM and the browser IIFE bundle are published; see Distribution bundles.

Yes. Each npm release version corresponds exactly to the Pega Infinity release it ships with, so floating ranges are not recommended; see Installation.

⬆️ Back to top

Security

Please review SECURITY.md for the vulnerability disclosure policy, supported versions, and the process for reporting a security issue privately.

Supply-chain hygiene recommendations:

• Pin the exact version in dependencies (not a range).
• Verify pre-built bundle integrity with SRI hashes before deploying to production (see Browser <script> IIFE).
• Run npm audit as part of your CI pipeline.

⬆️ Back to top

License

See LICENSE and the ConstellationJS Engine License for full terms.