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 lifecycle management
- API Integration - RTK Query with automatic caching and auth
- State Management - Redux Toolkit with dynamic injection
- Form Management - React Hook Form integration
- Analytics - Business analytics tracking
- Testing Utilities - Testing helpers and utilities

## 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​

- Usage Guide - Detailed usage patterns and examples
- API Documentation - Complete API reference
- SonarQube - Code quality metrics
- QA Environment - Test deployment
- Boilerplate - Reference implementation in `pui-react-boilerplate`

## Troubleshooting​

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