# `udp-react-enterprise-component-library`

The definitive React surface for building enterprise applications on the Univerus Development Platform. This is the top of a three-layer stack:

1. **`udp-stencil-component-library`** — core Web Components built with StencilJS.
2. **`udp-react-stencil-component-library`** — auto-generated React wrappers around the stencil components.
3. **`udp-react-enterprise-component-library`** *(this package)* — the public library apps consume. Adds the provider stack, auth + tenant integration, data-fetching hooks, shell chrome, and high-level page templates on top of the wrapped stencil components.

Full documentation is published to Univerus Hub — see [hub.dev.univerus.com](https://hub.dev.univerus.com) for the searchable TechDocs site generated from this package.

## Framework

- [App Provider](src/providers/README.md)
- [Shell](src/shell/README.md)
- [Config Service](src/configService/README.md)
- [Auth](src/utilities/auth/README.md) · [User](src/utilities/auth/user.md) · [Tenant](src/utilities/tenant/README.md)
- [Routes](src/routes/README.md)
- [Data Fetching](src/utilities/data-fetching.md)

More coming — forms, data browser, workflows, maps, charts.

## Getting Started

The fastest way to stand up a new UDP app is to clone the **[starter-kit](https://github.com/univerus/starter-kit)** — it comes pre-wired with the four files described below, Vite config, env files for each environment, and a working dashboard widget so you have something to `pnpm dev` against on day one.

```bash
git clone git@github.com:univerus/starter-kit.git my-app
cd my-app/frontend
pnpm install
pnpm dev
```

If you're wiring the library into an existing app instead, you need four files in `src/`:

### 1. `src/index.jsx` — entry point

Boot the runtime config **before** rendering, then mount `<App />`.

```jsx
import React from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';
import { loadUdpRuntimeConfig } from './udp-runtime-config';

loadUdpRuntimeConfig();
createRoot(document.getElementById('root')).render(<App />);
```

`loadUdpRuntimeConfig()` must run before any component that touches [`ConfigService`](src/configService/README.md) (auth, API URLs, product/tenant ids all read from it).

### 2. `src/udp-runtime-config.ts` — env → `ConfigService`

Maps Vite `import.meta.env.*` vars onto the shape `ConfigService` expects, then pushes it in via `loadConfigObject`:

```ts
import { ConfigService } from '@univerus/udp-react-enterprise-component-library';

export function loadUdpRuntimeConfig() {
  ConfigService.loadConfigObject({
    UNITY_API_DOMAIN: import.meta.env.REACT_APP_UNITY_API_DOMAIN ?? 'https://gateway.unitydev.ca',
    PRODUCT_API_DOMAIN: import.meta.env.REACT_APP_PRODUCT_API_DOMAIN ?? '',
    UNITY_PRODUCT_ID: import.meta.env.REACT_APP_UNITY_PRODUCT_ID ?? '',
    MSAL_CLIENT_ID: import.meta.env.REACT_APP_MSAL_CLIENT_ID ?? '',
    MSAL_TENANT: import.meta.env.REACT_APP_MSAL_TENANT ?? '',
    MSAL_API_ACCESS_SCOPE: import.meta.env.REACT_APP_MSAL_API_ACCESS_SCOPE ?? '',
    UNITY_URL: import.meta.env.REACT_APP_UNITY_URL ?? 'https://unitydev.ca',
    UNITY_TENANT_ID: import.meta.env.REACT_APP_UNITY_TENANT_ID ?? '',
    UNITY_VERTICAL_ID: import.meta.env.REACT_APP_UNITY_VERTICAL_ID ?? '',
    USE_AAD_REDIRECT: import.meta.env.REACT_APP_USE_AAD_REDIRECT === 'true',
    UNITY_ENVIRONMENT: import.meta.env.REACT_APP_UNITY_ENVIRONMENT,
    SIGN_IN_POLICY: import.meta.env.REACT_APP_SIGN_IN_POLICY ?? 'B2C_1A_signup_signin_v2',
  });
}
```

See the starter-kit's [`.env.development`](https://github.com/univerus/starter-kit/blob/development/frontend/.env.development) / `.env.production` etc. for the matching variable set per environment.

### 3. `src/App.jsx` — provider root

Wrap your routes in [`UdpAppProvider`](src/providers/README.md). It mounts theme, TanStack Query, MSAL/auth, user, tenant, router, and snackbar in the right order — you should not mount any of them yourself.

```jsx
import React from 'react';
import { UdpAppProvider } from '@univerus/udp-react-enterprise-component-library';
import Routes from './Routes';

const App = () => (
  <UdpAppProvider>
    <Routes />
  </UdpAppProvider>
);

export default App;
```

### 4. `src/Routes.jsx` — shell + route table

Render [`<Shell>`](src/shell/README.md) once at the top; put `<PrivateRoute>` / `<Redirect>` children inside it.

```jsx
import React, { lazy } from 'react';
import {
  PageContainer,
  PrivateRoute,
  Shell,
  Redirect,
} from '@univerus/udp-react-enterprise-component-library';
import AppBarControls from './appBarContent/AppBarControls';
import widgets from './dashboard/widgets';

const TestShell = lazy(() => import('./routes/test/TestShell'));

const Routes = () => (
  <Shell
    appContent={<AppBarControls />}
    navRoot='Home'
    siteName='My App'
    widgets={widgets}
  >
    <PrivateRoute exact path='/' render={props => <PageContainer isHomePage {...props} />} />
    <Redirect exact from='/home' to='/' />
    <PrivateRoute path='/test' exact component={TestShell} />
  </Shell>
);

export default Routes;
```

### What goes where

| File | Responsibility |
| --- | --- |
| `index.jsx` | Boot runtime config, create React root, render `<App />`. |
| `udp-runtime-config.ts` | Read env vars and push them into `ConfigService`. |
| `App.jsx` | Mount `UdpAppProvider` — the only place providers are wired. |
| `Routes.jsx` | Mount `<Shell>`, declare `PrivateRoute` / `PublicRoute` children. |

For the full reference — dashboard widgets, `.env.*` files, `app.manifest.json`, Vite config — clone the **[starter-kit](https://github.com/univerus/starter-kit)**.