electron-router-dom

electron-router-dom is an adapter designed to facilitate the integration of react-router-dom with Electron. It solves common issues encountered when using standard web routing in Electron environments, particularly regarding development vs. production consistency and multi-window support.

Key capabilities include:

• Production and Development Readiness: Works seamlessly across both environments.
• Window Routing Support: Enables each Electron window to maintain its own independent routing state.
• Query String Support: Allows the main process to send query strings to the renderer process.
• Type-safe API: Designed for a high-quality developer experience with TypeScript support.

The settings object is returned by the createElectronRouter function. It contains the configuration used to initialize the router. You can use this object to reuse settings across different parts of your application or to derive TypeScript types using typeof settings.

// Example of deriving a type from the settings object
type RouterSettings = typeof settings;

Version 2.0 introduces breaking changes due to a complete rewrite aimed at supporting React Router v6.4 Data APIs and improving type safety. Key changes include:

• API Simplification: createFileRoute and createURLRoute have been removed.
• Route Registration: Use the registerRoute method provided by the object returned from createElectronRouter instead of manual URL/file loading logic.
• Component Imports: The Route component is no longer exported from electron-router-dom. You must now import it from react-router-dom.
• Typing: ids and query keys are now typed for better intellisense and safety.
• Query Strings: Improved support for passing information between the main and renderer processes via query strings.

For a detailed step-by-step process, refer to the Migration Guide.

In v2, the Route component is no longer exported from electron-router-dom. You must import Route directly from react-router-dom. The Router component should be imported from your local configuration file.

// In your renderer routes file
import { Route } from 'react-router-dom'
import { Router } from '../lib/electron-router-dom'

To enable TypeScript intellisense for URLSearchParams methods (like .get()) based on the queryKeys you defined in createElectronRouter, you can augment the global URLSearchParams interface. This works for both the global object and the useSearchParams hook from react-router-dom.

Use the settings object returned by createElectronRouter to derive the types.

import { createElectronRouter, type Query } from 'electron-router-dom'

export const { Router, registerRoute, settings } = createElectronRouter({
  port: 4927,

  types: {
    ids: ['main'],
    queryKeys: ['name', 'version'],
  },
})

declare global {
  interface URLSearchParams {
    get<T extends typeof settings>(name: Query.Keys<T>): Query.Return
  }
}

In your main process (e.g., src/main/index.ts), use the registerRoute method to associate an Electron BrowserWindow with a specific route ID.

Important: Electron Router DOM manages loadURL and loadFile internally. Do not call these methods manually on the BrowserWindow to avoid conflicts.

import { registerRoute } from '../lib/electron-router-dom'
import path from 'path'

// Inside your window creation function:
registerRoute({
  id: 'main',
  browserWindow: window,
  htmlFile: path.join(__dirname, '../renderer/index.html'),
})

To migrate to v2, update your dependencies to the latest versions. Ensure your environment meets the following minimum version requirements:

• electron: >=17.0
• react: >=18.0
• react-router-dom: >=6.22.3

npm i react-router-dom@latest electron-router-dom@latest

In your renderer process (e.g., src/renderer/routes.tsx), use the Router component to define which react-router-dom routes belong to which window ID.

The Router component accepts props named after the IDs you defined in createElectronRouter. Each prop receives a fragment of react-router-dom routes.

import { Router } from '../lib/electron-router-dom'
import { Route } from 'react-router-dom'

import { MainScreen, AboutScreen, SearchScreen } from './screens'

export function AppRoutes() {
  return (
    <Router
      main={
        <>
          <Route path="/" element={<MainScreen />} />
          <Route path="/search" element={<SearchScreen />} />
        </>
      }
      about={<Route path="/" element={<AboutScreen />} />}
    />
  )
}

If you use a factory function to create Electron windows, you can ensure the id and query parameters are correctly typed by extracting the type from the registerRoute function returned by createElectronRouter.

1. Extract the Route type using Parameters<typeof registerRoute>[0].
2. Use Route['id'] and Route['query'] in your factory's props interface.

import { registerRoute } from './lib/electron-router-dom'

type Route = Parameters<typeof registerRoute>[0]

interface WindowProps extends Electron.BrowserWindowConstructorOptions {
  id: Route['id']
  query?: Route['query']
}

export function createWindow({ id, query, ...options }: WindowProps) {
  const window = new BrowserWindow(options)

  registerRoute({
    id,
    query,
    browserWindow: window,
    htmlFile: path.join(__dirname, '../renderer/index.html'),
  })

  return window
}