feat(FR-1683): migrate URL state management from use-query-params to nuqs for better React Transition support (#4646)

Resolves #4645 ([FR-1683](https://lablup.atlassian.net/browse/FR-1683))

## Background

Currently, the React application uses `use-query-params` for URL state management. However, this library has limitations when working with React's newer concurrent features, particularly React Transitions. As a result, users may experience delayed feedback when interacting with URL-driven state changes.

## Purpose

Modernize URL state management by adopting `nuqs`, which is specifically designed to handle React Transitions effectively. This will provide:

* **Faster user feedback**: Immediate visual responses during state transitions
* **Better React Transition support**: Seamless integration with React's concurrent rendering
* **Improved user experience**: More responsive UI with optimistic updates and proper loading states

## Key Changes

* Migrated from `use-query-params` to `nuqs` across all React components
* Replaced `QueryParamProvider` with `NuqsAdapter` in providers
* Updated pagination hooks to use `nuqs` API (`useQueryStates`, `parseAsInteger`)
* Created new helper utilities for GraphQL Result type handling
* Maintained type safety with proper TypeScript types and zod schemas
* Added legacy hooks for backward compatibility during migration

## Expected Outcomes

* Users see immediate visual feedback when changing filters, tabs, or pagination
* Smoother transitions between different views and states
* URL state changes feel more responsive and aligned with modern web application standards
* Better integration with React's concurrent features for future optimizations

**Checklist:**

- [ ] Documentation
- [ ] Minimum required manager version
- [ ] Specific setting for review
- [ ] Minimum requirements to check during review
- [x] Test case(s) to demonstrate the difference of before/after
  - Test URL state changes in session list page (filters, pagination, tabs)
  - Verify React Transitions feel more responsive
  - Check browser history navigation works correctly

[FR-1683]: https://lablup.atlassian.net/browse/FR-1683?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

Author: yomybaby

pnpm-lock.yaml

@@ -1,32 +1,32 @@
-const path = require("path");
+const path = require('path');
 module.exports = {
-  testEnvironment: "jsdom",
+  testEnvironment: 'jsdom',
   clearMocks: true,
-  setupFiles: ["jest-canvas-mock"],
-  setupFilesAfterEnv: ["<rootDir>/src/setupTests.ts"],
+  setupFiles: ['jest-canvas-mock'],
+  setupFilesAfterEnv: ['<rootDir>/src/setupTests.ts'],
   moduleNameMapper: {
-    "^backend\\.ai-ui$": path.resolve(
+    '^backend\\.ai-ui$': path.resolve(
       __dirname,
-      "../packages/backend.ai-ui/src",
+      '../packages/backend.ai-ui/src',
     ),
-    "^backend\\.ai-ui/(.*)$": path.resolve(
+    '^backend\\.ai-ui/(.*)$': path.resolve(
       __dirname,
-      "../packages/backend.ai-ui/src/$1",
+      '../packages/backend.ai-ui/src/$1',
     ),
-    "\\.svg": "<rootDir>/__test__/svg.mock.js",
-    "\\.(css|less|scss|sass)$": "identity-obj-proxy",
+    '\\.svg': '<rootDir>/__test__/svg.mock.js',
+    '\\.(css|less|scss|sass)$': 'identity-obj-proxy',
   },
   transformIgnorePatterns: [
-    "node_modules/(?!(backend\\.ai-ui)/)",
-    `!${path.resolve(__dirname, "../packages/backend.ai-ui/src")}`,
+    'node_modules/(?!(\\.pnpm/.+?/node_modules/(backend\\.ai-ui|nuqs)/|backend\\.ai-ui/|nuqs/))',
+    `!${path.resolve(__dirname, '../packages/backend.ai-ui/src')}`,
   ],
   transform: {
-    "^.+\\.(js|jsx|ts|tsx)$": "babel-jest",
+    '^.+\\.(js|jsx|ts|tsx)$': 'babel-jest',
   },
   collectCoverageFrom: [
-    "src/**/*.{js,jsx,ts,tsx}",
-    "!src/**/*.d.ts",
-    "!src/index.tsx",
-    "!src/reportWebVitals.ts",
+    'src/**/*.{js,jsx,ts,tsx}',
+    '!src/**/*.d.ts',
+    '!src/index.tsx',
+    '!src/reportWebVitals.ts',
   ],
 };

react/jest.config.js

@@ -46,6 +46,7 @@
     "lucide-react": "^0.552.0",
     "markdown-to-jsx": "^7.7.17",
     "marked": "^16.4.0",
+    "nuqs": "^2.7.3",
     "p-queue": "^8.1.1",
     "prettier": "^3.6.2",
     "prism-react-renderer": "^2.4.1",
@@ -72,13 +73,14 @@
     "typescript": "^5.7.2",
     "use-query-params": "^2.2.1",
     "uuid": "^13.0.0",
-    "web-vitals": "^3.5.2"
+    "web-vitals": "^3.5.2",
+    "zod": "^4.1.12"
   },
   "scripts": {
     "start": "craco start",
     "build": "pnpm run build:only && cp -r ./build/* ../build/rollup/",
     "build:only": "pnpm run relay && craco build",
-    "test": "NODE_OPTIONS='--no-deprecation' jest",
+    "test": "NODE_OPTIONS='$NODE_OPTIONS --no-deprecation --experimental-vm-modules' jest",
     "eject": "react-scripts eject",
     "relay": "relay-compiler",
     "relay:watch": "nodemon --watch schema.graphql --watch client-directives.graphql --exec 'pnpm run relay --watch'",
@@ -158,10 +160,10 @@
     "@storybook/react-webpack5": "^8.6.14",
     "@storybook/testing-library": "^0.2.2",
     "@tanstack/eslint-plugin-query": "^5.60.1",
-    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/user-event": "^14.6.1",
     "@types/big.js": "^6.2.2",
-    "@types/jest": "^29.5.14",
+    "@types/jest": "^30.0.0",
     "@types/lodash": "^4.17.20",
     "@types/node": "^22.9.0",
     "@types/react": "^19.2.2",
@@ -174,7 +176,7 @@
     "@types/relay-test-utils": "^19.0.0",
     "@types/uuid": "^11.0.0",
     "ajv": "^8.17.1",
-    "babel-jest": "^30.0.5",
+    "babel-jest": "^30.2.0",
     "babel-plugin-named-exports-order": "^0.0.2",
     "babel-plugin-react-compiler": "^1.0.0",
     "babel-plugin-relay": "^20.1.0",
@@ -188,9 +190,9 @@
     "eslint-plugin-storybook": "^0.11.1",
     "html-webpack-plugin": "5.6.3",
     "identity-obj-proxy": "^3.0.0",
-    "jest": "^29.7.0",
+    "jest": "^30.2.0",
     "jest-canvas-mock": "^2.5.2",
-    "jest-environment-jsdom": "^29.7.0",
+    "jest-environment-jsdom": "^30.2.0",
     "nodemon": "^3.1.7",
     "prop-types": "^15.8.1",
     "react-dev-utils": "^12.0.1",

react/package.json

@@ -19,6 +19,7 @@ import ServingPage from './pages/ServingPage';
 import VFolderNodeListPage from './pages/VFolderNodeListPage';
 import { Skeleton, theme } from 'antd';
 import { BAIFlex, BAICard } from 'backend.ai-ui';
+import { NuqsAdapter } from 'nuqs/adapters/react-router/v6';
 import React, { Suspense, FC } from 'react';
 import { useTranslation } from 'react-i18next';
 import {
@@ -558,7 +559,11 @@ const router = createBrowserRouter([
 ]);
 
 const App: FC = () => {
-  return <RouterProvider router={router} />;
+  return (
+    <NuqsAdapter>
+      <RouterProvider router={router} />
+    </NuqsAdapter>
+  );
 };
 
 export default App;

react/src/App.tsx

@@ -69,6 +69,17 @@ const fetchFn: FetchFunction = async (
         }
       })) || {};
 
+  if (result.errors) {
+    // NOTE: Starting from Relay 18.1.0, the error returned by @catch directive no longer has a message field,
+    // so we store the original message in the extensions.rawErrorMessage field.
+    // https://github.com/facebook/relay/releases/tag/v18.1.0
+    result.errors.forEach((error: any) => {
+      if (error.extensions && error.message) {
+        error.extensions.rawErrorMessage = error.message;
+      }
+    });
+  }
+
   return result;
 };
 

react/src/RelayEnvironment.ts

@@ -12,7 +12,7 @@ import {
 } from '../helper';
 import { INITIAL_FETCH_KEY, useSuspendedBackendaiClient } from '../hooks';
 import { ResourceSlotName, useResourceSlotsDetails } from '../hooks/backendai';
-import { useBAIPaginationOptionStateOnSearchParam } from '../hooks/reactPaginationQueryOptions';
+import { useBAIPaginationOptionStateOnSearchParamLegacy } from '../hooks/reactPaginationQueryOptions';
 import { useHiddenColumnKeysSetting } from '../hooks/useHiddenColumnKeysSetting';
 import { useThemeMode } from '../hooks/useThemeMode';
 import AgentDetailModal from './AgentDetailModal';
@@ -85,7 +85,7 @@ const AgentList: React.FC<AgentListProps> = ({
     baiPaginationOption,
     tablePaginationOption,
     setTablePaginationOption,
-  } = useBAIPaginationOptionStateOnSearchParam({
+  } = useBAIPaginationOptionStateOnSearchParamLegacy({
     current: 1,
     pageSize: 10,
   });

react/src/components/AgentList.tsx

@@ -9,7 +9,7 @@ import {
 } from '../helper';
 import { INITIAL_FETCH_KEY, useFetchKey } from '../hooks';
 import { ResourceSlotName, useResourceSlotsDetails } from '../hooks/backendai';
-import { useBAIPaginationOptionStateOnSearchParam } from '../hooks/reactPaginationQueryOptions';
+import { useBAIPaginationOptionStateOnSearchParamLegacy } from '../hooks/reactPaginationQueryOptions';
 import { useResourceGroupsForCurrentProject } from '../hooks/useCurrentProject';
 import { useHiddenColumnKeysSetting } from '../hooks/useHiddenColumnKeysSetting';
 import BAIProgressWithLabel from './BAIProgressWithLabel';
@@ -62,7 +62,7 @@ const AgentSummaryList: React.FC<AgentSummaryListProps> = ({
     baiPaginationOption,
     tablePaginationOption,
     setTablePaginationOption,
-  } = useBAIPaginationOptionStateOnSearchParam({
+  } = useBAIPaginationOptionStateOnSearchParamLegacy({
     current: 1,
     pageSize: 20,
   });

react/src/components/AgentSummaryList.tsx

@@ -9,7 +9,7 @@ import {
   useFetchKey,
   useSuspendedBackendaiClient,
 } from '../hooks';
-import { useBAIPaginationOptionStateOnSearchParam } from '../hooks/reactPaginationQueryOptions';
+import { useBAIPaginationOptionStateOnSearchParamLegacy } from '../hooks/reactPaginationQueryOptions';
 import { useSetBAINotification } from '../hooks/useBAINotification';
 import { useHiddenColumnKeysSetting } from '../hooks/useHiddenColumnKeysSetting';
 import { usePainKiller } from '../hooks/usePainKiller';
@@ -78,7 +78,7 @@ const ContainerRegistryList: React.FC<{
     baiPaginationOption,
     tablePaginationOption,
     setTablePaginationOption,
-  } = useBAIPaginationOptionStateOnSearchParam({
+  } = useBAIPaginationOptionStateOnSearchParamLegacy({
     current: 1,
     pageSize: 20,
   });

react/src/components/ContainerRegistryList.tsx

@@ -13,7 +13,7 @@ import {
   PendingSessionNodeListQuery$variables,
 } from 'src/__generated__/PendingSessionNodeListQuery.graphql';
 import { INITIAL_FETCH_KEY, useFetchKey, useWebUINavigate } from 'src/hooks';
-import { useBAIPaginationOptionStateOnSearchParam } from 'src/hooks/reactPaginationQueryOptions';
+import { useBAIPaginationOptionStateOnSearchParamLegacy } from 'src/hooks/reactPaginationQueryOptions';
 import { useBAISettingUserState } from 'src/hooks/useBAISetting';
 import { useCurrentResourceGroupValue } from 'src/hooks/useCurrentProject';
 
@@ -36,7 +36,7 @@ const PendingSessionNodeList: React.FC = () => {
     baiPaginationOption,
     tablePaginationOption,
     setTablePaginationOption,
-  } = useBAIPaginationOptionStateOnSearchParam({
+  } = useBAIPaginationOptionStateOnSearchParamLegacy({
     current: 1,
     pageSize: 10,
   });

react/src/components/PendingSessionNodeList.tsx

@@ -26,19 +26,46 @@ import { useTranslation } from 'react-i18next';
 import { graphql, useFragment } from 'react-relay';
 
 export type SessionNodeInList = NonNullable<SessionNodesFragment$data[number]>;
+
+const availableSessionSorterKeys = [
+  'name',
+  'scaling_group',
+  'type',
+  'cluster_mode',
+  'created_at',
+  'agent_ids',
+] as const;
+
+export const availableSessionSorterValues = [
+  ...availableSessionSorterKeys,
+  ...availableSessionSorterKeys.map((key) => `-${key}` as const),
+] as const;
+
+const isEnableSorter = (key: string) => {
+  return _.includes(availableSessionSorterKeys, key);
+};
+
 interface SessionNodesProps
-  extends Omit<BAITableProps<SessionNodeInList>, 'dataSource' | 'columns'> {
+  extends Omit<
+    BAITableProps<SessionNodeInList>,
+    'dataSource' | 'columns' | 'onChangeOrder'
+  > {
   sessionsFrgmt: SessionNodesFragment$key;
   onClickSessionName?: (session: SessionNodeInList) => void;
   disableSorter?: boolean;
+  onChangeOrder?: (
+    order: (typeof availableSessionSorterValues)[number] | null,
+  ) => void;
 }
 
 const SessionNodes: React.FC<SessionNodesProps> = ({
   sessionsFrgmt,
   onClickSessionName,
   disableSorter,
+  onChangeOrder,
   ...tableProps
 }) => {
+  'use memo';
   const { t } = useTranslation();
   const userRole = useCurrentUserRole();
   const baiClient = useSuspendedBackendaiClient();
@@ -101,7 +128,7 @@ const SessionNodes: React.FC<SessionNodesProps> = ({
             name
           );
         },
-        sorter: true,
+        sorter: isEnableSorter('name'),
         required: true,
         fixed: 'left',
       },
@@ -182,7 +209,7 @@ const SessionNodes: React.FC<SessionNodesProps> = ({
         dataIndex: 'scaling_group',
         title: t('session.ResourceGroup'),
         defaultHidden: true,
-        sorter: true,
+        sorter: isEnableSorter('scaling_group'),
         render: (__, session) =>
           session.scaling_group ? session.scaling_group : '-',
       },
@@ -191,15 +218,15 @@ const SessionNodes: React.FC<SessionNodesProps> = ({
         dataIndex: 'type',
         title: t('session.SessionType'),
         defaultHidden: true,
-        sorter: true,
+        sorter: isEnableSorter('type'),
         render: (__, session) => <BAISessionTypeTag sessionFrgmt={session} />,
       },
       {
         key: 'cluster_mode',
         dataIndex: 'cluster_mode',
         title: t('session.ClusterMode'),
         defaultHidden: true,
-        sorter: true,
+        sorter: isEnableSorter('cluster_mode'),
         render: (__, session) => (
           <BAISessionClusterMode sessionFrgmt={session} />
         ),
@@ -209,15 +236,15 @@ const SessionNodes: React.FC<SessionNodesProps> = ({
         dataIndex: 'created_at',
         title: t('session.CreatedAt'),
         defaultHidden: true,
-        sorter: true,
+        sorter: isEnableSorter('created_at'),
         render: (created_at: string) => dayjs(created_at).format('LLL') || '-',
       },
       (userRole === 'superadmin' || !baiClient._config.hideAgents) && {
         key: 'agent',
         dataIndex: 'agent_ids',
         title: t('session.Agent'),
         defaultHidden: false,
-        sorter: true,
+        sorter: isEnableSorter('agent_ids'),
         render: (__, session) => <BAISessionAgentIds sessionFrgmt={session} />,
       },
       userRole === 'superadmin' &&
@@ -242,6 +269,11 @@ const SessionNodes: React.FC<SessionNodesProps> = ({
         dataSource={filteredSessions}
         columns={columns}
         scroll={{ x: 'max-content' }}
+        onChangeOrder={(order) => {
+          onChangeOrder?.(
+            (order as (typeof availableSessionSorterValues)[number]) || null,
+          );
+        }}
         {...tableProps}
       />
     </>