For the underlying module API, see the Roles Module documentation.

React Roles V2 Cookbook

This cookbook demonstrates how a Fusion Framework React application requires Roles V2 access and
uses focused React hooks to display and claim role assignments.

When to use this cookbook

Use this example when an application needs to:

• render effective active-access assignments with useActiveAccessRoleAssignments;
• render and activate claimable assignments with useClaimableRoleAssignments;
• claim an assignment and automatically refresh both lists;
• stop initialization unless ProView.Admin.DevOps is active.

Roles checks in the browser support user-interface decisions. A trusted backend must still enforce
authorization for protected operations.

For the full production-to-test workflow this cookbook demonstrates end to end, see the
Roles V2 end-to-end adoption guide.

Configure Roles V2

src/config.ts
enables the app-scoped Roles module and requires the registered
ProView.Admin.DevOps access role:

enableRoles(configurator, (builder) => {
  builder.requireAccessRoles(['ProView.Admin.DevOps']);
});

Every configured role is required. Module initialization throws RequiredAccessRolesError before the app
renders when the signed-in account does not satisfy the requirement.

Show and claim roles

src/App.tsx
reads active and claimable roles through separate hooks:

import { useActiveAccessRoleAssignments, useClaimableRoleAssignments } from '@equinor/fusion-framework-react-components-roles';

const active = useActiveAccessRoleAssignments();
const claimable = useClaimableRoleAssignments();

src/index.ts
installs RolesProvider once around the application:

const appComponent = createElement(RolesProvider, undefined, createElement(App));

The provider owns one observable action/flow store. Each hook exposes focused loading, error, and
reload state. useClaimableRoleAssignments also exposes activation state; successful claims refresh both role
collections automatically.

Run the cookbook

The app expects a Fusion host that provides authentication and service discovery:

pnpm --filter @equinor/fusion-framework-cookbook-app-react-roles dev

For a standalone local app backed by deterministic Roles V2 HTTP responses, run:

pnpm --filter @equinor/fusion-framework-cookbook-app-react-roles dev:mock

This starts the app and the Fusion OpenAPI mock server together. The local
mocks/rolesv2.mock.ts
service uses defineRolesV2Mock to merge typed application policy onto the bundled rolesv2
contract. Its account map supplies recovery, operations, and reporting personas as ordinary data;
the framework-owned helper supplies paging, identity-aware routes, and session-isolated
activation/deactivation. The recovery persona first exposes a synthetic claimable role that grants
ProView.Admin.DevOps. After activation, the app loads and exposes a second claimable Reports
exporter assignment. The app still uses the production RolesClient; only service discovery and
HTTP responses are local.

Test with static Roles data

Use enableRolesMock for component tests that need known provider data without HTTP:

enableRolesMock(configurator, (mock) => {
  mock
    .setActiveAccessRoleAssignments([{ systemName: 'Fusion Apps', accessRoleName: 'Fusion.Apps.FullControl' }])
    .setConsolidatedClaimableRoleAssignments([{ id: 'assignment-id', claimableRole: { name: 'Report exporter' } }])
    .requireAccessRoles(['Fusion.Apps.FullControl']);
});

Consumers still receive the production Roles module provider (IRolesProvider). Use vi.spyOn on
provider methods such as activateClaimableRoleAssignment when a test needs a specific success,
failure, or pending response.

Test the real Roles client with generated responses

Use the normal enableRoles configuration with the Fusion OpenAPI mock server when the test should
cover RolesClient request paths, account resolution, response schemas, or caching:

pnpm --filter @equinor/fusion-framework-cookbook-app-react-roles mock:server

Point service discovery at http://localhost:4012/@fusion-mock/discovery. The bundled Fusion preset
includes rolesv2; the cookbook's local service then overrides only the operations used by the app.
This keeps production Roles configuration and request validation in the test path while making the
rendered role data repeatable.

The Playwright test starts both servers, claims the required role through the host recovery view,
verifies that the app loads without a refresh, compares the resolved app with its visual snapshot,
and proves that two concurrent browser contexts plus an in-place identity switch resolve independent
account policy:

pnpm --filter @equinor/fusion-framework-cookbook-app-react-roles test