@equinor/fusion-framework-dev-portal

Minimal development portal for building and testing Fusion Framework applications locally.

What Is It?

@equinor/fusion-framework-dev-portal provides a lightweight portal shell that mirrors the production Fusion portal layout — header, context selector, bookmark side sheet, person settings, and application routing — without the full production overhead. It is the portal component loaded by @equinor/fusion-framework-dev-server and @equinor/fusion-framework-cli when running apps locally.

Use this package when you need a portal host for local app development. For the recommended development workflow, pair it with @equinor/fusion-framework-dev-server.

Key Concepts

• Portal shell: A React application that renders the top bar, context selector, and an app mounting area.
• Application loader: Dynamically initializes and mounts a Fusion app by its appKey, handling manifest resolution, script loading, and teardown.
• Framework modules: The portal pre-configures telemetry, navigation, bookmarks, feature flags, analytics, AG Grid, Roles V2, and service integrations so loaded apps inherit a realistic environment.
• Help side sheet: Opens when an app calls useHelpCenter(). A production-shaped sidebar lists the current app's articles from the help service (typically local help docs served by ffc mock-server), with an article index for openHelp(), an FAQ page for openFaqs(), and a simple search over articles and FAQs for openSearch(). Release notes and other production-only pages show a "not supported in the dev portal" message. See Test help articles locally.
• Analytics in mock mode: Registers the Fusion portal's app-loaded, app-selected, and context-selected collectors. With --mock, it also sends analytics — including an app's useTrackFeature events — to the monitor service of the local mock server, the same way the Fusion portal sends them in production (portal.id is dev-portal). Without --mock, no analytics leave the browser; the fusionLogAnalytics feature flag still logs them to the console.
• Roles V2 integration: The person side sheet uses the shared compact Roles view, and the application loader can recover when an app requires access roles during initialization.
• Context navigation plugin: The portal enables enableContextNavigation from @equinor/fusion-framework-plugin-context-navigation so context changes and app switches keep the URL in sync automatically.

Installation

pnpm add @equinor/fusion-framework-dev-portal

Environment Variables

Set these in a .env file or in your server environment:

AG Grid License

To suppress AG Grid Enterprise license warnings during local development:

1. Add FUSION_SPA_AG_GRID_KEY=<your-key> to your .env file.
2. Start the dev portal with pnpm start.
3. Verify the browser console shows no AG Grid license warnings.

The license key is only used locally and must not be committed to the repository.

Quick Start

pnpm start

This launches the dev server with the portal loaded.

Public API

The package exports a single render function that mounts the portal into a DOM element:

import { render } from '@equinor/fusion-framework-dev-portal';

const el = document.createElement('div');
el.id = 'dev-portal';
document.body.appendChild(el);

// `framework` is a pre-configured Fusion Framework instance with Service Discovery and MSAL
render(el, { ref: framework });

Usage with @equinor/fusion-framework-dev-server

The dev server loads this portal automatically. A typical integration looks like:

import { createDevServer } from '@equinor/fusion-framework-dev-server';

const portalId = '@equinor/fusion-framework-dev-portal';
const devServer = await createDevServer({
  spa: {
    templateEnv: {
      portal: {
        id: portalId,
        tag: 'latest',
      },
    },
  },
  api: {
    serviceDiscoveryUrl: 'https://location.of.your.service.discovery',
  },
});

Architecture

The portal is composed of these internal parts:

• render — Entry point; creates a React root with theme, framework, and people-resolver providers.
• configure — Configures all framework modules (telemetry, navigation, context navigation, bookmarks, feature flags, analytics, AG Grid, services).
• analytics/ — configureAnalytics registers the portal's collectors and adapters, and sends analytics to the mock Monitor service only when resolveMockServerUrl() finds the mock server origin the dev server sets on window.FUSION_MOCK_SERVER_URL for --mock.
• Context configuration — enableContext wires the context module's path generator and path extractor to the shared context-navigation URL utilities.
• Router — Sets up routes with react-router via the navigation module; routes /apps/:appKey/* to the app loader.
• AppLoader — Resolves, initializes, and mounts a Fusion app by key; handles loading states and errors.
• Roles recovery — Wraps the application loader in AccessRoleBoundary so a user can activate an eligible claimable role and retry an app blocked by builder.requireAccessRoles.
• Header — Top bar with the Fusion logo, context selector, bookmark toggle, person settings, and the help side sheet.
• Help side sheet — Listens for @Portal::FusionHelp::open, lists GET /apps/{appKey}/articles in a collapsible sidebar, renders GET /articles/{slug} as markdown, lists GET /apps/{appKey}/faqs as expandable questions, and searches with POST /search. A labelled navigation landmark, aria-current, and stable data-testids (help-nav-article, help-article-title, help-search-result, help-not-found, help-unsupported) support Playwright and synthetic agents.
• Person side sheet — Renders <RolesView compact /> inside the React RolesProvider for active, claimable, and recently expired role assignments.
• ContextSelector — Wired to the current app's context module for searching and selecting context items.
• enableContextNavigation — Registers the portal-level context navigation plugin that reconciles the active context with the browser URL.

The portal enables @equinor/fusion-framework-module-roles against its authenticated account and service discovery configuration. See the Roles module guide for the provider contract and the React Roles components guide for the compact view and required-access recovery behavior.

Constraints

• This portal is for local development only and is not intended for production deployment.
• Visuals may differ from the production Fusion portal.
• The portal assumes MSAL and service discovery are configured in the parent framework instance.