@equinor/fusion-framework-module-navigation

Routing and navigation module for Fusion Framework with observable state management and automatic basename localization.

Features

• Path localization — consumers work with clean paths (/users) while the history stack receives full paths (/apps/my-app/users).
• Observable state — navigation state exposed as an RxJS observable (state$) with shareReplay semantics.
• Multiple history types — browser (pathname), hash (#/path), and memory (no URL changes).
• Router compatibility — createRouter() creates @remix-run/router instances wired to the framework history.
• Navigation blocking — intercept navigations with history.block() and optionally retry.
• Telemetry & events — dispatches NavigateEvent / NavigatedEvent and tracks actions via the telemetry module.

Safe operational telemetry

INavigationProvider extends the shared TelemetryConnectable contract. Navigation retains its existing Navigation::* notifications rather than adopting new operational record names.

After initialization, navigation connects available host telemetry without waiting for it during startup. Explicit setTelemetry(provider) takes precedence; setTelemetry(undefined) disables automatic hookup. Automatic wiring reports Navigation::navigated without per-action debug chatter.

Telemetry no longer includes locations, previous locations, route state, or action payloads. Detailed explicit-provider action events use the static Navigation::action name with the controlled action type only. Update consumers of the old dynamic names or payload fields. Navigation business events and routing behavior are unchanged. See Operational telemetry.

Installation

pnpm add @equinor/fusion-framework-module-navigation

Usage

Enable the module

import { enableNavigation } from '@equinor/fusion-framework-module-navigation';

// Minimal — basename only
enableNavigation(configurator, '/apps/my-app');

// Advanced — full configuration
enableNavigation(configurator, {
  configure: (config) => {
    config.setBasename('/apps/my-app');
    config.setHistory(createHistory('browser'));
  },
});

Programmatic navigation

const navigation = framework.modules.navigation;

navigation.push('/users');             // adds history entry
navigation.replace('/login');          // replaces current entry
navigation.push('/users', { id: 1 }); // with state

console.log(navigation.path.pathname); // '/users' — basename removed

Observable navigation state

import { filter } from 'rxjs';

navigation.state$.subscribe(({ action, location }) => {
  console.log(action, location.pathname); // 'PUSH' '/users'
});

navigation.state$.pipe(
  filter(({ action }) => action === 'POP'),
).subscribe(({ location }) => {
  console.log('Back/forward to', location.pathname);
});

Create href / URL

// basename = '/apps/my-app'
navigation.createHref('/users');
// → '/apps/my-app/users'

navigation.createURL('/users');
// → URL { pathname: '/apps/my-app/users', ... }

Router integration (legacy)

Note: Prefer @equinor/fusion-framework-react-router for new applications.

import type { AgnosticRouteObject } from '@remix-run/router';

const routes: AgnosticRouteObject[] = [
  { path: '/', element: <Home /> },
  { path: '/users/:id', element: <UserDetail /> },
];

const router = navigation.createRouter(routes);

Always use navigation.createRouter() instead of createBrowserRouter() directly—creating a router outside the provider breaks basename handling and state synchronisation.

History types

import { createHistory } from '@equinor/fusion-framework-module-navigation';

const browserHistory = createHistory('browser');
const hashHistory    = createHistory('hash');
const memoryHistory  = createHistory('memory');

Navigation blocking

const unblock = navigation.history.block((transition) => {
  if (hasUnsavedChanges) {
    showConfirmDialog(() => {
      unblock();          // remove blocker first
      transition.retry(); // then retry navigation
    });
  } else {
    unblock();
    transition.retry();
  }
});

API Reference

Functions

Classes

Interfaces & Types

Events

Configuration

See Also

• @equinor/fusion-framework-react-router — React Router integration
• Navigation Cookbook — Example application with routing