npm package: @plumile/backoffice-react
Description: React provider and pages for Plumile backoffice
Author: Olivier Hardy
Latest version: 0.1.87

# @plumile/backoffice-react

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

## Status

Specialized public package. This package is best suited to teams building a
Plumile-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

```bash
npm install @plumile/backoffice-react
```

Peer dependencies:

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

This package also depends on the Plumile 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`

### 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`
- detail and filter components
- picker and layout helpers

For the complete export list, see [`src/index.ts`](./src/index.ts).

## Quick Start

```tsx
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 Plumile Router DevTools bridge
- Performance Timeline marks and measures in Chrome DevTools
- custom router instrumentation for local diagnostics

Example:

```ts
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 Plumile entity manifests and backoffice routing concepts
- Relay integration is built around Plumile conventions, not every possible
  Relay application architecture
- consumers should keep domain-specific business components outside this package

## Related Docs

- [Backoffice Core README](../backoffice-core/README.md)
- [UI README](../ui/README.md)
- [Router README](../router/README.md)
- [Documentation Index](../../docs/index.md)