Integrating the Pega Constellation SDK into modern React frameworks like Next.js allows developers to build high-performance, custom front-ends while leveraging the full power of Pega's case management and workflow engine.

This guide documents the high-level steps required to integrate the Pega React SDK into a Next.js 16 application.

Note: This guide provides high-level code snippets to illustrate the concepts. Please refer to the attached project source code for the complete implementation details.

1. Environment Setup & Dependencies

First, we need to ensure the Next.js application has the correct dependencies installed. Pega's SDK requires specific packages for authentication, components, and the Constellation engine core. Install the dependencies:

npm install @pega/auth @pega/react-sdk-components @mui/material-nextjs

We also need development dependencies for the Constellation types and core definitions.

npm install --save-dev @pega/constellationjs @pega/pcore-pconnect-typedefs

Note: You may need to use --legacy-peer-deps depending on your npm version and peer dependency resolution.

Recommendation: For version 25 of the SDK, use @pega/[email protected] as version 25.1.10 has known CSS parsing issues.

2. Managing Static Assets

The Pega SDK relies on several static assets (HTML for auth redirects, JS for the bootstrap shell) that reside inside node_modules. Since Next.js serves static files from the public directory, we need a script to copy these over before the build. Create a script scripts/copy-assets.mjs:

Create a Node.js script that copies the following files from node_modules to your public folder:

1. @pega/auth/lib/oauth-client/authDone.html -> public/auth.html
2. @pega/auth/lib/oauth-client/authDone.js -> public/authDone.js
3. @pega/constellationjs/dist/bootstrap-shell.js -> public/constellation/bootstrap-shell.js
4. @pega/constellationjs/dist/bootstrap-shell.js.map -> public/constellation/bootstrap-shell.js.map (Optional)
5. @pega/constellationjs/dist/lib_asset.json -> public/constellation/lib_asset.json
6. The constellation-core folder.

Refer to scripts/copy-assets.mjs in the attached source code for the full implementation.

Update package.json to run this automatically:

"scripts": {
  "predev": "NODE_ENV=development node --experimental-modules ./scripts/copy-assets.mjs",
  "prebuild": "node --experimental-modules ./scripts/copy-assets.mjs"
}

3. Configuration

The SDK requires a configuration file to know how to connect to your Pega Infinity server.

Copy sdk-config.json: Copy the sdk-config.json file from the React SDK to the public folder of your Next.js application. This file requires your Pega Infinity server connection details.

Create sdk-local-component-map.js in your root: The SDK requires this file even if it is empty to initialize the component mapping system.

const localSdkComponentMap = {
  /* map end - DO NOT REMOVE */
};

export default localSdkComponentMap;

4. Material UI Integration

Since the Pega React SDK components are built using Material UI, proper theme configuration is essential for consistent rendering.

Create src/theme.ts: Define the Material UI theme that overrides default styles to match the Pega design system. This file handles palette colors, component overrides, and typography settings.

Refer to src/theme.ts in the attached source code for the complete theme definition.

5. Authentication Context

We need a React Context to manage the authentication lifecycle. This component will handle OAuth redirects and notify the app when the user is logged in.

 Create src/context/PegaAuthProvider.tsx: This context initializes the sdk-auth-manager, handles the login redirection, and listens for the SdkConstellationReady event.

// High-level structure
'use client';
import { createContext, useContext, useEffect, useState } from 'react';

const PegaAuthProvider = ({ children }) => {
  const [isAuthenticated, setIsAuthenticated] = useState(false);

  useEffect(() => {
    // Import sdk-auth-manager dynamically to avoid SSR issues
    import('@pega/auth/lib/sdk-auth-manager').then(
      async ({ loginIfNecessary }) => {
        document.addEventListener('SdkConstellationReady', () =>
          setIsAuthenticated(true),
        );
        loginIfNecessary({ appName: 'embedded', mainRedirect: false });
      },
    );
  }, []);

  return (
    <UserAuthContext.Provider value={{ isAuthenticated }}>
      {children}
    </UserAuthContext.Provider>
  );
};

Refer to src/context/PegaAuthProvider.tsx in the attached source code for the full implementation.

Create src/context/PegaAuthProvider.tsx: This context initializes the sdk-auth-manager, handles the login redirection, and listens for the SdkConstellationReady event.

// High-level structure
'use client';
import { createContext, useContext, useEffect, useState } from 'react';

const PegaAuthProvider = ({ children }) => {
  const [isAuthenticated, setIsAuthenticated] = useState(false);

  useEffect(() => {
    // Import sdk-auth-manager dynamically to avoid SSR issues
    import('@pega/auth/lib/sdk-auth-manager').then(
      async ({ loginIfNecessary }) => {
        document.addEventListener('SdkConstellationReady', () =>
          setIsAuthenticated(true),
        );
        loginIfNecessary({ appName: 'embedded', mainRedirect: false });
      },
    );
  }, []);

  return (
    <UserAuthContext.Provider value={{ isAuthenticated }}>
      {children}
    </UserAuthContext.Provider>
  );
};

Refer to src/context/PegaAuthProvider.tsx in the attached source code for the full implementation.

6. Initialization Context (PegaReadyContext)

This context is responsible for bootstrapping the Constellation engine (PCore, PConnect). It loads the standard portal elements.

Create src/context/PegaReadyContext.tsx:

It should include the loadMashup logic, dynamically import the RootComponent, and expose a helper function createCase.

'use client';
// Imports...

export const PegaReadyProvider = ({ children }) => {
  // Logic to:
  // 1. Initialize SDK Component Map
  // 2. Subscribe to PCore.onPCoreReady
  // 3. Register the Component Creator in the callback
  // 4. Call myLoadMashup('pega-root') to bootstrap

  // Expose createCase helper methods

  return (
    <PegaContext.Provider value={{ isPegaReady, createCase, PegaContainer }}>
      {children}
    </PegaContext.Provider>
  );
};

Refer to src/context/PegaReadyContext.tsx in the attached source code for the full implementation.

7. Integrating SDK logic in existing react components

Now we can build the actual page content.

Container (src/components/Embedded/index.tsx): Simply checks isAuthenticated and renders the home view

Home View (src/components/Embedded/Home.tsx): This is where the user interaction happens.

import { usePega } from '@/src/context/PegaReadyContext';

export default function Home() {
  const { createCase, PegaContainer } = usePega();

  const handleCreateCase = () => {
    createCase('Work-Class-Name', {
      pageName: 'pyEmbedAssignment',
      startingFields: { ... }
    });
  };

  return (
    <div>
      <button onClick={handleCreateCase}>Create Case</button>
      {/* This container renders the actual Pega UI when ready */}
      <PegaContainer />
    </div>
  );
}

Refer to src/components/Embedded/Home.tsx in the attached source code for the full implementation.

8. Wiring it all together

Finally, wrap your application in the providers inside app/layout.tsx.  

import PegaAuthProvider from '@/src/context/PegaAuthProvider';
import { PegaReadyProvider } from '@/src/context/PegaReadyContext';

export default function RootLayout({ children }) {
  return (
    <html lang='en'>
      <body>
        <PegaAuthProvider>
          <PegaReadyProvider>{children}</PegaReadyProvider>
        </PegaAuthProvider>
      </body>
    </html>
  );
}

Conclusion

By following these steps, you have successfully integrated the Pega Constellation SDK into a server-side rendered Next.js 16 application. You now have the ability to embed Pega workflows directly into your consumer-facing application while maintaining the robust business logic defined in Pega.

Important: Please refer to the attached nextjs-16-sdk.zip for the complete, working source code of this integration. Using the source code is recommended as it contains all the necessary types, helper functions, and exact import paths required for a successful build.