@plumile/backoffice-react

React provider, auth screens, routing scaffolds, and Relay helpers for Kronex-style backoffice applications.

Status

Specialized public package. This package is best suited to teams building a Kronex-style backoffice with entity manifests, Relay, and the shared UI layer.

Purpose

@plumile/backoffice-react is the React integration layer on top of:

• @plumile/backoffice-core for manifests, facets, and shared types
• @plumile/ui for the visual system
• @plumile/router for internal routing and instrumentation

It contains:

• BackofficeProvider
• auth screens and login flow helpers
• routing and page scaffolds
• backoffice hooks
• Relay environment and mutation helpers
• entity loading helpers and related UI building blocks

It does not try to become:

• a generic React application framework
• a second standalone component library
• a container for product-specific business logic

Installation

npm install @plumile/backoffice-react

Peer dependencies:

npm install react react-dom react-i18next i18next react-relay relay-runtime

This package also depends on the Kronex router, UI, and backoffice-core packages.

Main Public Surface

Provider and configuration

• BackofficeProvider
• useBackofficeConfig
• createBackofficeLazyValue
• config types such as BackofficeAuthConfig and BackofficeGraphQLConfig

Auth and session flows

• LoginFlow
• AcceptInvitationScreen
• PasswordResetRequestScreen
• PasswordResetCompleteScreen
• VerifyEmailScreen
• createUseAuth
• AuthRefreshNotice keeps the backoffice session-refresh subscription and fixed positioning in this package, while delegating its visual notice surface to InlineBanner from @plumile/ui.

Hooks and backoffice helpers

• useBackofficeListUrlState
• useConditionalSubscription
• useCopyToClipboard
• useRefetchNeededReload

Relay and mutation helpers

• RelayProvider
• configureRelayEnvironment
• getEnvironment
• resetRelayStore
• resolveMutationOutcome
• resolveAgentStartOutcome
• requireField
• requireLinkedRecordId

Backoffice-specific UI scaffolds

• BackofficeOverviewLayout
• BackofficeTabbedDetailShell
• BackofficeContentBoundary, BackofficeContentFallback, and related route fallbacks remain backoffice-specific because they encode Suspense, error-boundary reset, and routing behavior. Their error display composes the shared InlineBanner visual primitive from @plumile/ui.
• backoffice-specific detail components such as BackofficeLifecycleTimelineSection and BackofficeEntityLink
• EntityIdPickerDialog, which remains the backoffice picker integration for manifests, picker facets, Relay loading, scope, search, and selected IDs. The reusable picker visuals live in @plumile/ui as BackofficePickerShell, BackofficePickerList, and BackofficePickerRow.

Backoffice React no longer exports generic toolbar or detail-header wrappers. Use BackofficeToolbar, BackofficeListFooter, and BackofficePageHeader from @plumile/ui for visual composition; this package keeps the backoffice integration layer focused on manifests, routing, permissions, Relay, filters, and i18n.

Backoffice React also no longer exports the old generic detail wrappers and aliases: BackofficeDetailField, BackofficeDetailSection, BackofficeScopeStack, BackofficeContextPanel, BackofficeAuditMetadataPanel, BackofficeDetailPage, BackofficeCopyButton, BackofficeDetailTable, BackofficeDetailActionBar, BackofficeDetailBlock, BackofficeEmptyValue, BackofficeTechnicalFacts, BackofficeEntityRefLink, BackofficeFieldSet, BackofficeMetricGrid, BackofficeKpiStrip, BackofficeTimeline, BackofficeAuditTrail, and BackofficePayloadViewer. The timeline aliases were removed without compatibility wrappers; use AuditTimeline and TimelineEventRow from @plumile/ui for visual timelines. Use the canonical components instead: CopyableText, DataTable, MetricCard, MetricTileGroup, DashboardPanel, DashboardMetricGroup, DashboardQuickActions, DashboardStatusList, BackofficeKeyValueList, BackofficeDetailField, BackofficeDetailSection, BackofficeScopeStack, BackofficeAuditMetadataPanel, and AuditTimeline from @plumile/ui; direct React composition for empty/action/block wrappers; and BackofficeLifecycleTimelineSection and BackofficeEntityLink from @plumile/backoffice-react.

Backoffice React no longer exports generic payload viewers: BackofficeDetailPayload, BackofficePayloadInspectorSection, the legacy BackofficePayloadViewer alias, and formatJsonPayload were removed. Compose BackofficeDetailSection with BackofficePayloadViewer from @plumile/ui for payload, JSON, markdown, text, and code display.

For the complete export list, see src/index.ts.

Quick Start

import { BackofficeProvider } from '@plumile/backoffice-react';

export function App(): JSX.Element {
  return (
    <BackofficeProvider
      entityManifest={entityManifest}
      auth={auth}
      graphql={graphql}
    />
  );
}

Instrumentation

BackofficeProvider forwards router instrumentations to the internal createRouter(...) call. This is useful when you want to expose:

• the Kronex Router DevTools bridge
• Performance Timeline marks and measures in Chrome DevTools
• custom router instrumentation for local diagnostics

Example:

import {
  createDevtoolsBridgeInstrumentation,
  createPerformanceTimelineInstrumentation,
} from '@plumile/router';
import { BackofficeProvider } from '@plumile/backoffice-react';

const instrumentations = [
  createDevtoolsBridgeInstrumentation(),
  createPerformanceTimelineInstrumentation(),
];

<BackofficeProvider
  entityManifest={entityManifest}
  auth={auth}
  graphql={graphql}
  instrumentations={instrumentations}
/>;

If instrumentations is omitted, routing still works normally.

Validation Notes

• public helpers that are pure or mostly pure should have focused unit tests
• provider behavior should remain covered by React tests
• package documentation should describe the main composition flows rather than every low-level implementation detail

Limitations

• this package assumes Kronex entity manifests and backoffice routing concepts
• Relay integration is built around Kronex conventions, not every possible Relay application architecture
• consumers should keep domain-specific business components outside this package

Related Docs

• Backoffice Core README
• UI README
• Router README
• Documentation Index