Skip to main content

Getting Started

Welcome to the PUI App SDK - the ICE MT UI Platform Application SDK for building React micro-frontend applications with integrated cross-cutting concerns.

Overview​

The PUI App SDK provides:

  • Micro-Frontend Architecture - CMicroApp guest/host lifecycle, navigation links, inter-app communication
  • API Integration - RTK Query with automatic caching and auth, plus legacy HTTP client with 401 retry
  • State Management - Redux Toolkit with dynamic injection, listener middleware, and error middleware
  • Form Management - React Hook Form integration with input masks, date pickers, combos, and layout components
  • Analytics & LogRocket - Business analytics tracking with automatic LogRocket identification, event buffering, and throttling
  • Authentication - OAuth/IDP login, session management, automatic LogRocket identity lifecycle, and auth subpath helpers
  • Session Management - Idle timeout, expiry warnings, session renewal, and ready-made UI components
  • Testing Utilities - renderWithRedux, renderWithRouter, Testing Library re-exports, and RenderWithStateAddOns
  • Environment & Utilities - Environment detection, URL helpers, themes, PII redaction, and TypeScript decorators

Prerequisites​

  • Node.js: Version 20 or higher
  • pnpm: Version 8 or higher
  • React: Compatible with @elliemae/app-react-dependencies ^4.26.0

Installation​

pnpm add @elliemae/pui-app-sdk

Required Peer Dependencies​

pnpm add @elliemae/app-react-dependencies \
  @elliemae/pui-app-bridge \
  @elliemae/pui-theme \
  @elliemae/ssf-guest \
  @elliemae/ssf-host

Quick Start​

1. Create App Configuration​

Create app.config.json:

{
  "appId": "your-app-id",
  "activeEnv": "localhost",
  "sessionTimeoutWarnInterval": "7200000",
  "sessionTimeoutInterval": "9000000",
  "serviceEndpoints": {
    "api": "https://api.example.com"
  }
}

2. Initialize Your Micro-App​

import {
  CMicroApp,
  configureStore,
  setAppConfig,
  listenStorageEvents,
  initServiceWorker,
} from '@elliemae/pui-app-sdk';
import { createRoot } from 'react-dom/client';
import appConfig from './app.config.json';
import { logger } from './utils/logger'; // Your logger instance

// Setup
setAppConfig(appConfig);
listenStorageEvents();

let app = null;
let store = null;
let root = null;

// Lifecycle callbacks
const onInit = ({ history, homeRoute }) => {
  store = configureStore({}, history);
};

const onMount = ({ containerId }) => {
  root = createRoot(document.getElementById(containerId));
  root.render(<Application />);
};

const onUnmount = () => {
  root?.unmount();
  return null;
};

// Create micro-app instance
app = CMicroApp.getInstance({
  logger,
  onInit,
  onMount,
  onUnmount,
});

initServiceWorker('/base-path');

3. Set Up Application Root​

import { AppRoot } from '@elliemae/pui-app-sdk';

export const Application = () => {
  // app and store are defined in the initialization code above
  const appProps = app.getProps();

  return (
    <AppRoot
      store={store}
      history={appProps.history}
      theme={appProps.theme}
      manageSession
    >
      <AppRoutes />
    </AppRoot>
  );
};

4. Define Routes​

import { Routes, Route } from 'react-router-dom';
import { Page } from '@elliemae/pui-app-sdk';

export const AppRoutes = () => (
  <Routes>
    <Route path="/" element={<Layout />}>
      <Route
        index
        element={
          <Page pageTitle="Dashboard">
            <Dashboard />
          </Page>
        }
      />
    </Route>
  </Routes>
);

Core Concepts​

API Integration​

Recommended: Use RTK Query for seamless API integration:

import { useInjectQuery } from '@elliemae/pui-app-sdk';
import { resourcesApi } from './api/resources';

export const Layout = () => {
  // Inject RTK Query API
  useInjectQuery({ api: resourcesApi });
  // ...
};

→ Learn more about RTK Query

State Management​

For non-API state, use Redux with dynamic injection:

import { useInjectReducer, useInjectSaga } from '@elliemae/pui-app-sdk';

export const Layout = () => {
  useInjectReducer({ key: 'ui', reducer });
  useInjectSaga({ key: 'workflows', saga: workflowSagas });
  // ...
};

→ Learn more about State Management

Making API Calls​

Recommended: Use RTK Query for API integration with automatic caching, request deduplication, and loading states:

import { createApi } from '@reduxjs/toolkit/query/react';
import { sdkBaseQuery } from '@elliemae/pui-app-sdk';

export const resourcesApi = createApi({
  reducerPath: 'resourcesApi',
  baseQuery: sdkBaseQuery({ baseUrl: '/v1' }),
  endpoints: (builder) => ({
    getResources: builder.query<Resource[], void>({
      query: () => ({ url: '/resources', method: 'GET' }),
    }),
  }),
});

export const { useGetResourcesQuery } = resourcesApi;

// Use in components
const { data, isLoading } = useGetResourcesQuery();

→ Learn more about RTK Query API Integration
→ Legacy HTTP Client approach

Forms​

Build validated forms with React Hook Form:

import { Form as SDKForm } from '@elliemae/pui-app-sdk';

<SDKForm onSubmit={handleSubmit}>
  <FormFields />
</SDKForm>;

→ Learn more about Forms

Micro-Frontends​

Embed child applications:

import { GuestMicroApp, history } from '@elliemae/pui-app-sdk';

<GuestMicroApp id="child-app" history={history} />;

→ Learn more about Micro-Frontends

Analytics & Scripting Objects​

Track events and communicate between apps:

import { CMicroApp } from '@elliemae/pui-app-sdk';

const app = CMicroApp.getInstance();
const analytics = await app.getObject('analytics');

→ Learn more about Analytics
→ Learn more about Scripting Objects

Testing​

The SDK provides testing helpers for components with Redux and Router:

import { renderWithRedux } from '@elliemae/pui-app-sdk';

renderWithRedux(<MyComponent />, {
  initialState: { user: { name: 'John' } },
});

→ Learn more about Testing

Project Structure​

Recommended structure for SDK-based applications:

my-app/
├── app/
│   ├── api/              # RTK Query API definitions
│   ├── data/             # Redux slices (for non-API state)
│   ├── route/            # Route definitions
│   ├── sideeffect/       # Redux Sagas (for complex workflows)
│   ├── utils/            # Utility functions
│   ├── view/             # UI components
│   ├── app.config.json   # App configuration
│   └── index.tsx         # Entry point
└── package.json

→ See detailed structure in Usage Guide

Next Steps​

  • Usage Guide - Detailed examples and patterns
  • API Documentation - Complete API reference
  • Examples - Run pnpm run storybook to view component examples
  • Boilerplate - Check pui-react-boilerplate for a complete working example

Resources​

Troubleshooting​

For common issues and solutions, see the Usage Guide Troubleshooting section.