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.
This package is React specific but is also only used by SDK packages that depend on React. If you are using a different framework, you can safely ignore this package.
Installation
To install this package, you need to have access to the private @sdk
npm scope.
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)
The SDK Router package is designed to work with the most common routing libraries. We plan to add more router adapters in the future.
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.