Sync query parameters with a MobX store and React Router.
This was originally developed in VocaDB/vocadb#965 as a part of VocaDB.
See VocaDB's search page.
- React
- React Router (v6)
- MobX
yarn add @vocadb/route-sphere or npm i @vocadb/route-sphere
There are three custom hooks, depending on the use case: useStoreWithUpdateResults, useStoreWithPagination and useStoreWithRouteParams. These hooks are defined as below:
const useStoreWithUpdateResults = <TRouteParams>(store: StoreWithUpdateResults<TRouteParams>): void;
const useStoreWithPagination = <TRouteParams>(store: StoreWithPagination<TRouteParams>): void;
const useStoreWithRouteParams = <TRouteParams>(store: StoreWithRouteParams<TRouteParams>): void;The useStoreWithUpdateResults updates search results whenever the routeParams property changes. The StoreWithUpdateResult interface is defined as below:
interface StoreWithUpdateResults<TRouteParams> extends StoreWithRouteParams<TRouteParams> {
readonly clearResultsByQueryKeys: (keyof TRouteParams)[];
/** Called when search results should be cleared. */
onClearResults?: () => void;
updateResults(clearResults: boolean): Promise<void>;
}The useStoreWithUpdateResults hook determines if search results should be cleared by comparing the current and previous values. If that's the case, the onClearResults callback is called.
- CommentIndex.tsx and CommentListStore.ts (demo)
- SongLyrics.tsx and SongLyricsStore.ts (demo)
- SongRankings.tsx and RankingsStore.ts (demo)
The useStoreWithPagination hook is a helper hook that is composed of the useStoreWithUpdateResults and useStoreWithRouteParams hooks. The StoreWithPagination interface is defined as below:
interface StoreWithPagination<TRouteParams> extends StoreWithUpdateResults<TRouteParams> {
/** Called when search results should be cleared. */
onClearResults(): void;
}- ArtistSongs.tsx and ArtistSongsStore.ts (demo)
- DiscussionFolders.tsx and DiscussionIndexStore.ts (demo)
- SearchIndex.tsx and SearchStore.ts (demo)
- SongListDetails.tsx and SongListStore.ts (demo)
The useStoreWithRouteParams hook updates a store that implements the StoreWithRouteParams interface when a route changes, and vice versa. The StoreWithRouteParams interface is defined as below:
interface StoreWithRouteParams<TRouteParams> {
routeParams: TRouteParams;
validateRouteParams(data: any): data is TRouteParams;
}The validateRouteParams function validates route params and should return true if and only if the passed data is valid. Validation happens every time location (not URL) changes, which means, when the page is first loaded, when the back/forward buttons on the browser are clicked, and when the page is navigated to a new location programmatically by using the useNavigate hook. Note that the <Link> component uses the useNavigate hook internally.
The routeParams property gets and sets the state of the store.
Reactions should be independent: Does your code rely on some other reaction having to run first? If that is the case, you probably either violated the first rule, or the new reaction you are about to create should be merged into the one it is depending upon. MobX does not guarantee the order in which reactions will be run.
Source: Running side effects with reactions · MobX
We use JSON schema to validate route params. Use typescript-json-schema project/directory/tsconfig.json TYPE to generate schema from a TypeScript type. For more information, see YousefED/typescript-json-schema.
- DiscussionIndexRouteParams.schema.json generated from DiscussionIndexRouteParams
- ArtistSongsRouteParams.schema.json generated from ArtistSongsRouteParams
- SearchRouteParams.schema.json generated from SearchRouteParams
- SongListRouteParams.schema.json generated from SongListRouteParams