@equinor/fusion-framework-react-router

Thin integration layer between React Router v7 and the Fusion Framework. It adds Fusion-specific behaviour — navigation module wiring, typed fusion context injection, a file-style route DSL, and manifest-ready route schemas — while keeping the full power of React Router.

Features

• Fusion navigation integration — reads history and basename from the Fusion navigation module automatically.
• Typed fusion context everywhere — loaders, actions, components, and error elements receive fusion.modules and fusion.context without threading props or React contexts.
• File-style route DSL — layout, index, route, prefix helpers replace hand-built RouteObject trees.
• Route schema generation — handle.route metadata can be turned into a flat, machine-readable schema for manifests, portals, and documentation.
• Module augmentation — extend RouterContext and RouterHandle to type your own context and handle fields.
• Vite plugin — statically transforms DSL calls into optimised React Router data routes at build time.

Installation

pnpm add @equinor/fusion-framework-react-router

Prerequisites

• React 18+ / React DOM 18+
• @equinor/fusion-framework-react-module
• @equinor/fusion-framework-module-navigation configured in your app

Usage

1. Define page modules

Each page module exports a default component. Optionally export clientLoader, action, handle, and ErrorElement.

// src/pages/ProductPage.tsx
import type {
  LoaderFunctionArgs,
  RouteComponentProps,
  RouterHandle,
} from '@equinor/fusion-framework-react-router';

export const handle = {
  route: {
    description: 'Product page',
    params: { id: 'Product identifier' },
    search: { filter: 'Product type filter' },
  },
} satisfies RouterHandle;

export async function clientLoader({ params, fusion }: LoaderFunctionArgs<{ id: string | undefined }>) {
  const client = fusion.modules.http.createHttpClient('products');
  return client.json(`/products/${params.id}`);
}

export default function ProductPage({ loaderData }: RouteComponentProps<{ name: string }>) {
  return <h1>{loaderData.name}</h1>;
}

2. Build the route tree with the DSL

// src/pages/index.ts
import { layout, index, route, prefix } from '@equinor/fusion-framework-react-router/routes';

export const pages = layout('./MainLayout.tsx', [
  index('./HomePage.tsx'),
  prefix('products', [
    index('./ProductsPage.tsx'),
    route(':id', './ProductPage.tsx'),
  ]),
]);

3. Mount the Router

// src/Router.tsx
import { Router } from '@equinor/fusion-framework-react-router';
import { pages } from './pages';

export default function AppRouter() {
  return <Router routes={pages} />;
}

Passing custom context

Extend RouterContext via module augmentation, then pass the context to <Router>:

// router-context.d.ts
declare module '@equinor/fusion-framework-react-router' {
  interface RouterContext {
    queryClient: import('@tanstack/react-query').QueryClient;
  }
}

// src/Router.tsx
import { Router } from '@equinor/fusion-framework-react-router';
import { QueryClient } from '@tanstack/react-query';
import { pages } from './pages';

const queryClient = new QueryClient();
export default function AppRouter() {
  return <Router routes={pages} context={{ queryClient }} />;
}

Loaders and components then access fusion.context.queryClient with full type safety.

Generating route schemas

import { toRouteSchema } from '@equinor/fusion-framework-react-router/schema';
import { pages } from './pages';

const schema = await toRouteSchema(pages);
// => [['/', 'Home page'], ['products/:id', 'Product page', { params: { id: 'Product identifier' } }]]

Vite plugin

Enable the DSL transform so route definitions are rewritten to standard RouteObject code at build time:

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { reactRouterPlugin } from '@equinor/fusion-framework-react-router/vite-plugin';

export default defineConfig({
  plugins: [react(), reactRouterPlugin()],
});

API Reference

Components

| Export | Description | |---|---| | Router | Integrates React Router v7 with Fusion Framework. Accepts routes, optional loader, and optional context. |

Hooks & Context

| Export | Description | |---|---| | useRouterContext() | Returns the current FusionRouterContext (modules + context). Throws if used outside <Router>. | | routerContext | React Router context key used internally to pass the Fusion context to loaders and actions. | | FusionRouterContextProvider | React context provider for FusionRouterContext. Used internally by <Router>. |

Route DSL (/routes entry point)

| Export | Description | |---|---| | layout(file, children) | Layout route wrapping children with a shared component containing <Outlet />. | | index(file, schema?) | Index route rendered at the parent's path. | | route(path, file, children?, schema?) | Standard route with a URL path and optional children. | | prefix(path, children) | Path-only grouping — prepends a segment to children without rendering a component. |

Schema (/schema entry point)

| Export | Description | |---|---| | toRouteSchema(nodes) | Converts a route tree (DSL nodes or legacy RouteObject[]) to a flat RouteSchemaEntry[]. |

Vite Plugin (/vite-plugin entry point)

| Export | Description | |---|---| | reactRouterPlugin(options?) | Vite plugin that transforms DSL calls into React Router RouteObject code at build time. |

Key Types

| Type | Description | |---|---| | FusionRouterContext | Object containing modules (Fusion modules instance) and context (custom context). | | RouterContext | Extensible interface for custom context (extend via module augmentation). | | RouterHandle | Handle interface with route: RouterSchema and extensible custom fields. | | RouterSchema | Schema with description, params, and search for a single route. | | RouteComponentProps<TData, TActionData> | Props received by route components: loaderData, actionData, fusion. | | LoaderFunctionArgs<TParams> | Arguments passed to clientLoader functions. | | ActionFunctionArgs<TParams> | Arguments passed to action functions. | | ErrorElementProps<TError> | Props received by error boundary components: error, fusion. | | RouteNode | Base interface for DSL route nodes. | | RouteSchemaEntry | Tuple format: [path, description] or [path, description, { params?, search? }]. |

Configuration

The <Router> component reads history and basename from the Fusion navigation module. Ensure your app configures @equinor/fusion-framework-module-navigation before mounting the router.

For the Vite plugin, pass { debug: true } to reactRouterPlugin() to enable verbose transformation logging during development.

For a complete end-to-end example, see the cookbooks/app-react-router cookbook.