@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.

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

| Factory argument | Class | Description | |---|---|---| | 'browser' | BrowserHistory | Pathname-based routing via the History API. Default. | | 'hash' | BrowserHistory (hash stack) | Hash-fragment routing (#/path). No server config needed. | | 'memory' | MemoryHistory | In-memory history. Ideal for widgets, tests, and SSR. |

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

| Export | Description | |---|---| | enableNavigation(configurator, opts?) | Registers the navigation module on a configurator. | | createHistory(type, ...args) | Factory for BrowserHistory, hash-based BrowserHistory, or MemoryHistory. |

Classes

| Export | Description | |---|---| | NavigationProvider | Module provider — manages state, localization, and lifecycle. | | NavigationConfigurator | Fluent config builder with Zod validation. | | BrowserHistory | History backed by browser pushState / replaceState. | | MemoryHistory | History backed by in-memory storage. |

Interfaces & Types

| Export | Description | |---|---| | INavigationProvider | Public contract for the navigation provider. | | INavigationConfigurator | Configuration shape (basename, history, telemetry, eventProvider). | | History | History instance contract (observable state + navigation methods). | | Path | { pathname, search, hash } | | Location | Path extended with state and key. | | To | string \| Partial<Path> — target for navigation operations. | | Action | Enum: Pop, Push, Replace. | | NavigationUpdate | { delta, action, location } emitted by state$. |

Events

| Event | When | Cancelable | |---|---|---| | NavigateEvent (onNavigate) | Before navigation | Yes | | NavigatedEvent (onNavigated) | After navigation | No |

Configuration

| Option | Type | Default | Description | |---|---|---|---| | basename | string | undefined | URL path prefix stripped from / prepended to consumer paths. | | history | History | Browser history (or memory in Node) | History instance created via createHistory(). | | telemetry | ITelemetryProvider | Auto-resolved | Tracks navigation events and errors. | | eventProvider | IEventModuleProvider | Auto-resolved | Dispatches onNavigate / onNavigated events. |

See Also

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