ptech-shell-react

Production React adapters for PTECH Module Federation shell apps.

This package bridges framework/runtime libraries into the contracts exported by ptech-shell-sdk.

Exports

Root entry:

import {
  createMsalUserService,
  createReactRouterNavigationAdapter,
} from 'ptech-shell-react';

The root entry stays react-router runtime-free. It exports:

• createMsalUserService
• createReactRouterNavigationAdapter
• related MSAL and navigation adapter types

React Router subpath:

import {
  ShellRouterBridge,
  ShellRouterProvider,
  detectBasenameFromKnownRoots,
} from 'ptech-shell-react/react-router';

Import this subpath only in code that has React Router available.

MSAL bootstrap subpath:

import {
  createMsalInstance,
  createMsalRedirectHooks,
  planInteractiveAuthRedirect,
} from 'ptech-shell-react/msal';

Import ./msal when bootstrapping MSAL at app startup (no React required).

MSAL React subpath:

import { MsalAuthGate, useAuth } from 'ptech-shell-react/msal-react';

Import ./msal-react only under <MsalProvider>.

MSAL User Service

Use createMsalUserService in production hosts that authenticate through MSAL.

import { registerService, TOKENS } from 'ptech-shell-sdk';
import { createMsalUserService } from 'ptech-shell-react';
import { createMsalRedirectHooks } from 'ptech-shell-react/msal';

registerService(
  TOKENS.userService,
  createMsalUserService({
    msal,
    defaultScopes: ['api://example/access_as_user'],
    loginMode: 'redirect',
    logoutMode: 'redirect',
    tokenInteractionMode: 'redirect',
    ...createMsalRedirectHooks({ redirectAttemptCap: 2 }),
  }),
);

MSAL Bootstrap and Auth Gate

Use createMsalInstance once at startup, wrap the app with MsalProvider, then gate rendering with MsalAuthGate:

import { MsalProvider } from '@azure/msal-react';
import { createMsalInstance } from 'ptech-shell-react/msal';
import { MsalAuthGate } from 'ptech-shell-react/msal-react';

const msal = await createMsalInstance(msalConfig);

<MsalProvider instance={msal}>
  <MsalAuthGate requireAccessToken tokenScopes={['api://example/access_as_user']}>
    <App />
  </MsalAuthGate>
</MsalProvider>

For direct MSAL hook usage (outside the shell UserService contract), use useAuth from ptech-shell-react/msal-react.

The adapter implements the SDK UserService contract:

• getSnapshot
• getSession
• acquireAccessToken
• login
• logout
• subscribe

Host-specific claim mapping belongs in mapUser; keep product-specific mapping out of this package.

React Router Navigation

Use createReactRouterNavigationAdapter when wiring React Router to the SDK NavigationService contract directly.

import { registerService, TOKENS } from 'ptech-shell-sdk';
import { createReactRouterNavigationAdapter } from 'ptech-shell-react';

const adapter = createReactRouterNavigationAdapter({ basename: '/audit-tool' });
registerService(TOKENS.navigation, adapter.service);

App-Owned Router

Use ShellRouterProvider when the app owns its top-level router.

import { ShellRouterProvider } from 'ptech-shell-react/react-router';

export function AppRoot() {
  return (
    <ShellRouterProvider basename="/audit-tool">
      <AppRoutes />
    </ShellRouterProvider>
  );
}

ShellRouterProvider creates/registers the navigation adapter and renders a BrowserRouter.

Host-Owned Router

Use ShellRouterBridge when a remote is mounted inside a router owned by the host. Do not nest another router in this topology.

import { registerService, TOKENS } from 'ptech-shell-sdk';
import { createReactRouterNavigationAdapter } from 'ptech-shell-react';
import { ShellRouterBridge } from 'ptech-shell-react/react-router';

const adapter = createReactRouterNavigationAdapter({ basename: '/t/demo/audit-tool' });
registerService(TOKENS.navigation, adapter.service);

export function RemoteRoot() {
  return (
    <>
      <ShellRouterBridge adapter={adapter} basename="/t/demo/audit-tool" />
      <RemoteRoutes />
    </>
  );
}

Basename Detection

Prefer an explicit basename. detectBasenameFromKnownRoots is a fallback for older remotes that need to infer a host mount prefix from the current path.

import { detectBasenameFromKnownRoots } from 'ptech-shell-react/react-router';

const basename = detectBasenameFromKnownRoots(window.location.pathname, [
  'audit-tool',
  'settings',
]);

Build

npm run build -w ptech-shell-react

The build has four entries:

• .: MSAL user service and navigation adapter, without importing React Router or MSAL React.
• ./react-router: React Router components and helpers.
• ./msal: MSAL bootstrap utilities (createMsalInstance, redirect loop breaker).
• ./msal-react: MsalAuthGate and useAuth (requires @azure/msal-react).