Pre-Release (next) - React 19

[odinr]

Fusion Framework React 19 preview 🚀

Tag: next
Branch: react-19

This branch is where we roll out React 19 support for Fusion Framework. It’s meant for application teams that are already on React 18 (or heading there soon) and want to kick the tyres on the next generation of the stack.

We’re aiming to ship the final React 19-compatible release in early 2026, so this preview is the best place to try things out and tell us what feels good (or not) before everything is locked in.

Warning

This is a preview on the next tag. Things can still move around – APIs, types, and behaviour may change before the final release. Treat it as a safe playground, not a long‑term production baseline (a fancy sandbox, not your production pillow 🧪).

Important

When testing this preview, install all @equinor/fusion-framework-* packages with the @next tag. Mixing @next and latest will give you type errors and subtle runtime bugs because the peer dependency ranges won’t line up.

Note

This work is part of Upgrade to React 19 (#3663) and related routing/navigation improvements. It’s built for apps running on React 18 or 19.

---

🚨 Breaking changes

React 19 & React 18+ requirement

Several React‑facing packages now target React 19 and require React 18 or 19 as peer dependencies:

View all affected packages (14 packages)

• @equinor/fusion-framework-react-app
• @equinor/fusion-framework-react
• @equinor/fusion-framework-react-router
• @equinor/fusion-framework-react-module
• @equinor/fusion-framework-react-module-http
• @equinor/fusion-framework-react-module-context
• @equinor/fusion-framework-react-module-event
• @equinor/fusion-framework-react-module-bookmark
• @equinor/fusion-framework-react-module-signalr
• @equinor/fusion-framework-react-components-bookmark
• @equinor/fusion-framework-react-components-people-provider
• @equinor/fusion-observable
• @equinor/fusion-query
• @equinor/fusion-framework-dev-portal

Important

Peer dependencies now require react and react-dom in the range ^18.0.0 || ^19.0.0. React 16 and 17 are no longer supported for these packages.

What this means in practice:

• If you’re still on React 16 or 17, move to React 18+ first (no clever workaround here, sorry 🙃).
• Once you’re on React 18 or 19, update your Fusion dependencies to the @next tag and test against this preview.

Navigation module refactor

@equinor/fusion-framework-module-navigation has undergone a complete refactor with React Router v7 upgrade:

Breaking Changes:

Change	Impact	Migration
React Router v7 upgrade	@remix-run/router upgraded from v1.8.0 to v1.23.0	TypeScript types may require as any assertions in some cases (see warning below)
Configurator exports	NavigationConfigurator and INavigationConfigurator exported from separate interface files	Public API unchanged, internal structure changed
createHistory path	Moved from root to lib/create-history	Public API unchanged, internal path changed
Types reorganization	Types moved from ./types to ./lib/types	Public API unchanged, internal path changed
navigator deprecated	Use history instead	See code example below

// Before
const nav = navigation.navigator;

// After
const history = navigation.history;

Caution

TypeScript types may not fully resolve with React Router v7, requiring type assertions (as any) in some cases when using useRouter with RouterProvider. This is a known limitation and will be addressed in future updates.

New Features:

• Added NavigationProvider and INavigationProvider exports
• Added enableNavigation helper function
• Added navigation events (NavigateEvent, NavigatedEvent)
• Improved history implementations with state management

React app bootstrap

@equinor/fusion-framework-react-app now requires React 18+ and uses React 18's createRoot API:

• renderComponent and renderApp functions are no longer deprecated
• These functions now use the createRoot API internally

Tip

Make sure you’re on React 18+ and then rely on renderApp/renderComponent instead of wiring ReactDOM.render yourself. The helpers now use createRoot for you, so you can delete some boilerplate and pretend it was always this clean ✨.

---

✨ New features

React Router DSL API

New package @equinor/fusion-framework-react-router provides a DSL on top of React Router v7 that plugs straight into Fusion.

Key features:

Feature	Description
Fusion Navigation Integration	Automatically connects to Fusion navigation module for history and basename management
File-based Route DSL	Uses declarative helpers (layout, index, route, prefix) to define routes in a type-safe, file-based style
Fusion Context Injection	Automatically injects Fusion modules and custom context into all route loaders, actions, and components via a typed fusion object
Lazy Loading	Supports automatic code splitting with lazy route loading using import.meta.resolve()
Route Schema Generation	Generates route schemas for documentation and app manifests
Vite Plugin Support	Optional Vite plugin for static analysis and optimized route tree generation

Using the DSL (recommended for new apps):

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

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

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

Backward compatibility: plain React Router objects still work

Important

The Router component accepts both the new DSL format and traditional React Router RouteObject[] arrays. Existing applications using navigation.createRouter() or plain React Router route objects can migrate incrementally.

You can pass standard React Router route objects directly to Router while migrating to the DSL:

import { Router } from '@equinor/fusion-framework-react-router';
import type { RouteObject } from 'react-router';

// Traditional React Router route objects still work
const routes: RouteObject[] = [
  {
    path: '/',
    element: <RootLayout />,
    children: [
      {
        index: true,
        element: <HomePage />,
      },
      {
        path: 'products',
        element: <ProductsPage />,
        loader: async ({ fusion }) => {
          // Fusion context is automatically injected
          const { http } = fusion.modules;
          return http.fetch('/api/products');
        },
      },
    ],
  },
];

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

What gets injected:

Context	Available Properties
Loaders/Actions	fusion.modules (all Fusion modules), fusion.context (custom context)
Components	loaderData, actionData, fusion as props
Error Elements	error, fusion as props

// Example: Using fusion in a loader
export async function clientLoader({ fusion, params }) {
  const { http, context } = fusion.modules;
  const user = fusion.context.user;
  return http.fetch(`/api/products/${params.id}`);
}

// Example: Using fusion in a component
export default function ProductPage({ loaderData, fusion }) {
  const { http } = fusion.modules;
  // Component logic...
}

Migration path:

Tip

New applications: Start with the DSL from day one

Existing applications: Continue using RouteObject[] arrays and migrate to DSL incrementally

Deprecated: NavigationProvider.createRouter() is deprecated but still works (emits telemetry warnings)

CLI enhancements

Raw Imports Support

@equinor/fusion-framework-cli now automatically includes the rawImportsPlugin in Vite configurations, enabling ?raw imports for markdown files:

import readmeContent from '../../README.md?raw';

Serve Command

New app serve command to serve built applications with the dev-portal:

pnpm fusion-framework-cli app serve
pnpm fusion-framework-cli app serve --port 5000
pnpm fusion-framework-cli app serve --dir ./dist --host 0.0.0.0

Type exports

Observable

@equinor/fusion-observable now exports actions via a dedicated export path for better tree-shaking:

import type { Action, ActionTypes } from '@equinor/fusion-observable/actions';

React app

@equinor/fusion-framework-react-app now exports the Fusion type:

import type { Fusion } from '@equinor/fusion-framework-react-app';

React module

@equinor/fusion-framework-react-module now exports the following types:

• Modules
• ModulesInstanceType
• AnyModule
• ModulesInstance

import type { Modules, ModulesInstanceType } from '@equinor/fusion-framework-react-module';

Telemetry

@equinor/fusion-framework-module-telemetry now exports the TelemetryScope enum:

import { TelemetryScope } from '@equinor/fusion-framework-module-telemetry';

Import plugins

Markdown raw plugin

@equinor/fusion-imports now exports createMarkdownRawPlugin for esbuild markdown ?raw import support:

import { createMarkdownRawPlugin } from '@equinor/fusion-imports';

Import meta resolve plugin

@equinor/fusion-imports now exports createImportMetaResolvePlugin for Vite plugin support:

import { createImportMetaResolvePlugin } from '@equinor/fusion-imports';

Vite plugin for raw imports

New package @equinor/fusion-framework-vite-plugin-raw-imports for handling ?raw imports in library mode:

import readmeContent from '../../README.md?raw';

Note

The plugin is automatically included when using @equinor/fusion-framework-cli for building applications.

Navigation module deprecation

@equinor/fusion-framework-module-navigation now deprecates NavigationProvider.createRouter method in favor of @equinor/fusion-framework-react-router.

The createRouter method now emits a deprecation warning via telemetry when called.

Tip

Replace navigation.createRouter(routes) with the React Router DSL from @equinor/fusion-framework-react-router/routes.

---

📦 Package updates

Dev portal

• Upgraded to React 19 compatible versions of fusion-react components
• Upgraded react-router-dom from v6 to v7.9.5 for React 19 compatibility (backward-compatible upgrade)

Cookbooks

Multiple cookbooks have been migrated to use the new React Router DSL API:

• @equinor/fusion-framework-cookbook-app-react-bookmark-advanced
• @equinor/fusion-framework-cookbook-app-react-charts
• @equinor/fusion-framework-cookbook-app-react-people

New cookbook

• @equinor/fusion-framework-cookbook-app-react-styling: New cookbook demonstrating React 19 compatible version of @equinor/fusion-react-styles

Documentation

• Added React Router module documentation page to vue-press
• Improved Fusion React Router README with clearer quick start, route DSL overview, and examples

Testing

• Added test suite for renderApp function in @equinor/fusion-framework-react-app using Vitest and React Testing Library

---

📝 Summary

This pre-release includes:

• Major React 19 upgrade across multiple packages
• New React Router DSL API package for modern route definitions
• CLI enhancements with raw imports support and serve command
• Multiple type exports for better TypeScript support and tree-shaking
• Navigation module refactor with React Router v7
• Cookbook migrations to demonstrate new routing patterns

---

✅ Quick upgrade checklist for existing apps

• Upgrade React first: Move your app to react/react-dom ^18.0.0 || ^19.0.0 and align @types/react across the workspace.
• Stick to one tag: Upgrade all @equinor/fusion-framework-* dependencies to the same @next version – don’t mix latest and next (future you will thank you 💚).
• Modernise your bootstrap: If you use @equinor/fusion-framework-react-app, make sure your entrypoint uses the renderApp/renderComponent helpers (now backed by createRoot).
• Adopt the router integration: For apps with navigation + routing, prefer @equinor/fusion-framework-react-router’s Router + DSL helpers (layout, index, route, prefix) over hand‑rolled React Router wiring.
• Plan navigation migration: If you rely on NavigationProvider.createRouter, keep it for now but treat it as legacy. New code should use the router package; migrate existing routes over time.
• Compare with cookbooks: Use the updated cookbooks (app-react-bookmark-advanced, app-react-charts, app-react-people, app-react-styling) as working examples of recommended setup.

---

🔗 Related Issues

Main/Parent Issue

• Upgrade to React 19 #3663 - Upgrade to React 19 - Primary initiative for React 19 support across Fusion Framework

Sub-issues

• Closes React 19: Remove Material-UI from @equinor/fusion-react-styles (v1.0.0) #3698 (React 19 compatibility)
• Closes Make Module-Navigation React 19 Compatible #3699 (Navigation module refactor)
• Closes Deprecate React 17 support and make React 18+ the new standard #3504 (React 18+ requirement)

---

📦 Installation

This pre-release is published with the next tag.

Warning

Install all Fusion Framework packages with the @next tag to prevent type mismatches. Do not mix @next and latest versions. All @equinor/fusion-framework-* packages must use the same tag (@next) to ensure type compatibility and prevent runtime errors.

# Upgrade all Fusion Framework packages to @next
pnpm upgrade -r @equinor/fusion-framework-*@next

# Or install specific packages
pnpm add @equinor/fusion-framework-react@next @equinor/fusion-framework-react-router@next

---

💬 Feedback

Tried the React 19 preview and have thoughts, ideas, or sharp edges to report? Please drop any feedback you have in this thread – everything from "it just worked 🎉" to "this API feels weird" is valuable.

If something’s on your mind while testing (confusing error, docs gap, migration friction, missing helper, etc.), write it down here rather than keeping it in your head. Even small comments help us shape the final release.