Router SDK

Utilitis to manage the routing of your application. Other SDK packages might depend on this package to provide advanced routing features without coupling them to a specific routing library.

Installation

To integrate the SDK Router package into your project, use the following command with your preferred package manager:

npm install @sdk/router-react react react-dom

Then, wrap your app with the RouterProvider to make routing logic accessible throughout your component tree:

import { RouterProvider, useRouterAdapterNextPages } from '@sdk/router-react';
import { useRouter } from 'next/router';
 
function App() {
  const routerAdapter = useRouterAdapterNextPages(useRouter());
 
  return (
    <RouterProvider {...routerAdapter}>
      <Component />
    </RouterProvider>
  );
}

Router Adapters

Different router adapters are available to use with the RouterProvider. These adapters are used to interact with the router of the underlying framework (i.e.: Nextjs, Tanstack Router, React Router). The following adapters are available:

• useRouterAdapterNextPages: Adapter for Next.js legacy page routing (opens in a new tab)

Make sure that you have the necessary peer dependencies installed for the router adapter you are using. For example, if you are using the useRouterAdapterNextPages adapter, you need to have next installed.

Routing

If you need to navigate in your app, you can use the router provided by your framework. This SDK package however provides a set of advanced tools to manage some complexer use-cases involving a router.

useHistoryAwareRouter

The useHistoryAwareRouter hook provides a way to navigate in your app while keeping track of the navigation history. This is useful when you need to navigate back to the previous page or to a specific page in the history.

import { useHistoryAwareRouter } from '@sdk/router-react';
 
function Component() {
  const { navigateToMatchedHistory } = useHistoryAwareRouter();
 
  const handleClick = () => {
    navigateToMatchedHistory({
      matchPathname: (pathname) => pathname.includes('/projects'),
      fallbackRoute: '/projects';
    });
  };
 
  return (
      <button onClick={handleClick}>Go back to projects</button>
  );
}

In this example, the navigateToMatchedHistory function navigates to the first page in the history that matches the provided condition, matching the last route in the history that starts with /projects. If no page matches the condition, the fallback route is used. The underlying history stack works on a LIFO (Last In First Out) basis. The last route visited is the first one checked.

  [History Stack / Last In First Out]
  - /tasks/1               <- Current page
  - /tasks                 <- First route in history that is checked, no match
  - /projects/1/tasks      <- Seconed route in hostory that is checked, this is a match
  - /projects/1
  - /projects
  - /home

Assuming the browser is currently on route /tasks/1, the navigateToMatchedHistory function will navigate to /projects/1/tasks as it matches the "starts with /projects" condition.

useQueryState

The useQuesryState hook provides a way to manage the query parameters of the current URL. This is useful when you need to update the query parameters of the current URL without navigating to a new page. It works the same way as the useState hook, but it also updates the query parameters of the current URL.

If a default value is provided in the second parameter, the query parameter will be set to that value when the component mounts.

import { useQueryState } from '@sdk/router-react';
 
function Component() {
  const [query, setQuery] = useQueryState('page', '1');
 
  const handleClick = () => {
    setQuery('2');
  };
 
  return <button onClick={handleClick}>Go to page 2</button>;
}

In this example, the setQuery function updates the query parameter page of the current URL to 2. The URL will be updated to /current-page?page=2 without navigating to a new page.

useLocalStorageQueryState

The useLocalStorageQueryState hook provides a way to manage the query parameters of the current URL and store them in the local storage. This is useful when you need to persist the query parameters of the current URL across page reloads.

import { useLocalStorageQueryState } from '@sdk/router-react';
 
function Component() {
  const [query, setQuery] = useLocalStorageQueryState('sort', 'asc');
 
  return (
    <>
      <button onClick={() => setQuery('desc')}>Sort Descending</button>
      <button onClick={() => setQuery('asc')}>Sort Ascending</button>
    </>
  );
}

In this example, the setQuery function updates the query parameter sort of the current URL to desc or asc. The URL will be updated to /current-page?sort=desc or /current-page?sort=asc without navigating to a new page. The query parameter will be stored in the local storage and will persist across page reloads.

useContentLayoutSwitch

This is a helpfull utility to handle the common pattern of switching content layouts between a list and a tile based view. It will store it's value in the local storage and the query parameter.

useContentSortingSelection

This is a helpfull utility to handle the common pattern of sorting content by different criteria. It will store it's value in the local storage and the query parameter.