refactor(query-state): migrate query param state management to nuqs (#30184)

Co-authored-by: Stephen Zhou <38493346+hyoban@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
2026-06-14 20:41:21 +08:00 · 2025-12-29 11:24:54 +08:00
parent 446df6b50d
commit 3ae7788933
28 changed files with 1336 additions and 1328 deletions
@@ -21,8 +21,8 @@ vi.mock('use-context-selector', async () => {
    useContext: () => ({ hasEditPermission: true }),
  }
 })
-vi.mock('@/hooks/use-tab-searchparams', () => ({
-  useTabSearchParams: () => ['Recommended', vi.fn()],
+vi.mock('nuqs', () => ({
+  useQueryState: () => ['Recommended', vi.fn()],
 }))
 vi.mock('@/service/use-explore', () => ({
  useExploreAppList: () => mockUseExploreAppList(),
@@ -20,7 +20,6 @@ import { usePluginDependencies } from '@/app/components/workflow/plugin-dependen
 import { NEED_REFRESH_APP_LIST_KEY } from '@/config'
 import { useAppContext } from '@/context/app-context'
 import ExploreContext from '@/context/explore-context'
-import { useTabSearchParams } from '@/hooks/use-tab-searchparams'
 import { DSLImportMode } from '@/models/app'
 import { importDSL } from '@/service/apps'
 import { fetchAppDetail } from '@/service/explore'
@@ -64,10 +63,7 @@ const Apps = ({
  }

  const [currentType, setCurrentType] = useState<AppModeEnum[]>([])
-  const [currCategory, setCurrCategory] = useTabSearchParams({
-    defaultTab: allCategoriesEn,
-    disableSearchParams: true,
-  })
+  const [currCategory, setCurrCategory] = useState<AppCategories | string>(allCategoriesEn)

  const {
    data,
@@ -1,363 +0,0 @@
-/**
- * Test suite for useAppsQueryState hook
- *
- * This hook manages app filtering state through URL search parameters, enabling:
- * - Bookmarkable filter states (users can share URLs with specific filters active)
- * - Browser history integration (back/forward buttons work with filters)
- * - Multiple filter types: tagIDs, keywords, isCreatedByMe
- *
- * The hook syncs local filter state with URL search parameters, making filter
- * navigation persistent and shareable across sessions.
- */
-import { act, renderHook } from '@testing-library/react'
-
-// Import the hook after mocks are set up
-import useAppsQueryState from './use-apps-query-state'
-
-// Mock Next.js navigation hooks
-const mockPush = vi.fn()
-const mockPathname = '/apps'
-let mockSearchParams = new URLSearchParams()
-
-vi.mock('next/navigation', () => ({
-  usePathname: vi.fn(() => mockPathname),
-  useRouter: vi.fn(() => ({
-    push: mockPush,
-  })),
-  useSearchParams: vi.fn(() => mockSearchParams),
-}))
-
-describe('useAppsQueryState', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-    mockSearchParams = new URLSearchParams()
-  })
-
-  describe('Basic functionality', () => {
-    it('should return query object and setQuery function', () => {
-      const { result } = renderHook(() => useAppsQueryState())
-
-      expect(result.current.query).toBeDefined()
-      expect(typeof result.current.setQuery).toBe('function')
-    })
-
-    it('should initialize with empty query when no search params exist', () => {
-      const { result } = renderHook(() => useAppsQueryState())
-
-      expect(result.current.query.tagIDs).toBeUndefined()
-      expect(result.current.query.keywords).toBeUndefined()
-      expect(result.current.query.isCreatedByMe).toBe(false)
-    })
-  })
-
-  describe('Parsing search params', () => {
-    it('should parse tagIDs from URL', () => {
-      mockSearchParams.set('tagIDs', 'tag1;tag2;tag3')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      expect(result.current.query.tagIDs).toEqual(['tag1', 'tag2', 'tag3'])
-    })
-
-    it('should parse single tagID from URL', () => {
-      mockSearchParams.set('tagIDs', 'single-tag')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      expect(result.current.query.tagIDs).toEqual(['single-tag'])
-    })
-
-    it('should parse keywords from URL', () => {
-      mockSearchParams.set('keywords', 'search term')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      expect(result.current.query.keywords).toBe('search term')
-    })
-
-    it('should parse isCreatedByMe as true from URL', () => {
-      mockSearchParams.set('isCreatedByMe', 'true')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      expect(result.current.query.isCreatedByMe).toBe(true)
-    })
-
-    it('should parse isCreatedByMe as false for other values', () => {
-      mockSearchParams.set('isCreatedByMe', 'false')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      expect(result.current.query.isCreatedByMe).toBe(false)
-    })
-
-    it('should parse all params together', () => {
-      mockSearchParams.set('tagIDs', 'tag1;tag2')
-      mockSearchParams.set('keywords', 'test')
-      mockSearchParams.set('isCreatedByMe', 'true')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      expect(result.current.query.tagIDs).toEqual(['tag1', 'tag2'])
-      expect(result.current.query.keywords).toBe('test')
-      expect(result.current.query.isCreatedByMe).toBe(true)
-    })
-  })
-
-  describe('Updating query state', () => {
-    it('should update keywords via setQuery', () => {
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({ keywords: 'new search' })
-      })
-
-      expect(result.current.query.keywords).toBe('new search')
-    })
-
-    it('should update tagIDs via setQuery', () => {
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({ tagIDs: ['tag1', 'tag2'] })
-      })
-
-      expect(result.current.query.tagIDs).toEqual(['tag1', 'tag2'])
-    })
-
-    it('should update isCreatedByMe via setQuery', () => {
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({ isCreatedByMe: true })
-      })
-
-      expect(result.current.query.isCreatedByMe).toBe(true)
-    })
-
-    it('should support partial updates via callback', () => {
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({ keywords: 'initial' })
-      })
-
-      act(() => {
-        result.current.setQuery(prev => ({ ...prev, isCreatedByMe: true }))
-      })
-
-      expect(result.current.query.keywords).toBe('initial')
-      expect(result.current.query.isCreatedByMe).toBe(true)
-    })
-  })
-
-  describe('URL synchronization', () => {
-    it('should sync keywords to URL', async () => {
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({ keywords: 'search' })
-      })
-
-      // Wait for useEffect to run
-      await act(async () => {
-        await new Promise(resolve => setTimeout(resolve, 0))
-      })
-
-      expect(mockPush).toHaveBeenCalledWith(
-        expect.stringContaining('keywords=search'),
-        { scroll: false },
-      )
-    })
-
-    it('should sync tagIDs to URL with semicolon separator', async () => {
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({ tagIDs: ['tag1', 'tag2'] })
-      })
-
-      await act(async () => {
-        await new Promise(resolve => setTimeout(resolve, 0))
-      })
-
-      expect(mockPush).toHaveBeenCalledWith(
-        expect.stringContaining('tagIDs=tag1%3Btag2'),
-        { scroll: false },
-      )
-    })
-
-    it('should sync isCreatedByMe to URL', async () => {
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({ isCreatedByMe: true })
-      })
-
-      await act(async () => {
-        await new Promise(resolve => setTimeout(resolve, 0))
-      })
-
-      expect(mockPush).toHaveBeenCalledWith(
-        expect.stringContaining('isCreatedByMe=true'),
-        { scroll: false },
-      )
-    })
-
-    it('should remove keywords from URL when empty', async () => {
-      mockSearchParams.set('keywords', 'existing')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({ keywords: '' })
-      })
-
-      await act(async () => {
-        await new Promise(resolve => setTimeout(resolve, 0))
-      })
-
-      // Should be called without keywords param
-      expect(mockPush).toHaveBeenCalled()
-    })
-
-    it('should remove tagIDs from URL when empty array', async () => {
-      mockSearchParams.set('tagIDs', 'tag1;tag2')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({ tagIDs: [] })
-      })
-
-      await act(async () => {
-        await new Promise(resolve => setTimeout(resolve, 0))
-      })
-
-      expect(mockPush).toHaveBeenCalled()
-    })
-
-    it('should remove isCreatedByMe from URL when false', async () => {
-      mockSearchParams.set('isCreatedByMe', 'true')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({ isCreatedByMe: false })
-      })
-
-      await act(async () => {
-        await new Promise(resolve => setTimeout(resolve, 0))
-      })
-
-      expect(mockPush).toHaveBeenCalled()
-    })
-  })
-
-  describe('Edge cases', () => {
-    it('should handle empty tagIDs string in URL', () => {
-      // NOTE: This test documents current behavior where ''.split(';') returns ['']
-      // This could potentially cause filtering issues as it's treated as a tag with empty name
-      // rather than absence of tags. Consider updating parseParams if this is problematic.
-      mockSearchParams.set('tagIDs', '')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      expect(result.current.query.tagIDs).toEqual([''])
-    })
-
-    it('should handle empty keywords', () => {
-      mockSearchParams.set('keywords', '')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      expect(result.current.query.keywords).toBeUndefined()
-    })
-
-    it('should handle undefined tagIDs', () => {
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({ tagIDs: undefined })
-      })
-
-      expect(result.current.query.tagIDs).toBeUndefined()
-    })
-
-    it('should handle special characters in keywords', () => {
-      // Use URLSearchParams constructor to properly simulate URL decoding behavior
-      // URLSearchParams.get() decodes URL-encoded characters
-      mockSearchParams = new URLSearchParams('keywords=test%20with%20spaces')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      expect(result.current.query.keywords).toBe('test with spaces')
-    })
-  })
-
-  describe('Memoization', () => {
-    it('should return memoized object reference when query unchanged', () => {
-      const { result, rerender } = renderHook(() => useAppsQueryState())
-
-      const firstResult = result.current
-      rerender()
-      const secondResult = result.current
-
-      expect(firstResult.query).toBe(secondResult.query)
-    })
-
-    it('should return new object reference when query changes', () => {
-      const { result } = renderHook(() => useAppsQueryState())
-
-      const firstQuery = result.current.query
-
-      act(() => {
-        result.current.setQuery({ keywords: 'changed' })
-      })
-
-      expect(result.current.query).not.toBe(firstQuery)
-    })
-  })
-
-  describe('Integration scenarios', () => {
-    it('should handle sequential updates', async () => {
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({ keywords: 'first' })
-      })
-
-      act(() => {
-        result.current.setQuery(prev => ({ ...prev, tagIDs: ['tag1'] }))
-      })
-
-      act(() => {
-        result.current.setQuery(prev => ({ ...prev, isCreatedByMe: true }))
-      })
-
-      expect(result.current.query.keywords).toBe('first')
-      expect(result.current.query.tagIDs).toEqual(['tag1'])
-      expect(result.current.query.isCreatedByMe).toBe(true)
-    })
-
-    it('should clear all filters', () => {
-      mockSearchParams.set('tagIDs', 'tag1;tag2')
-      mockSearchParams.set('keywords', 'search')
-      mockSearchParams.set('isCreatedByMe', 'true')
-
-      const { result } = renderHook(() => useAppsQueryState())
-
-      act(() => {
-        result.current.setQuery({
-          tagIDs: undefined,
-          keywords: undefined,
-          isCreatedByMe: false,
-        })
-      })
-
-      expect(result.current.query.tagIDs).toBeUndefined()
-      expect(result.current.query.keywords).toBeUndefined()
-      expect(result.current.query.isCreatedByMe).toBe(false)
-    })
-  })
-})
@@ -0,0 +1,248 @@
+import type { UrlUpdateEvent } from 'nuqs/adapters/testing'
+import type { ReactNode } from 'react'
+/**
+ * Test suite for useAppsQueryState hook
+ *
+ * This hook manages app filtering state through URL search parameters, enabling:
+ * - Bookmarkable filter states (users can share URLs with specific filters active)
+ * - Browser history integration (back/forward buttons work with filters)
+ * - Multiple filter types: tagIDs, keywords, isCreatedByMe
+ */
+import { act, renderHook, waitFor } from '@testing-library/react'
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
+import useAppsQueryState from './use-apps-query-state'
+
+const renderWithAdapter = (searchParams = '') => {
+  const onUrlUpdate = vi.fn<(event: UrlUpdateEvent) => void>()
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <NuqsTestingAdapter searchParams={searchParams} onUrlUpdate={onUrlUpdate}>
+      {children}
+    </NuqsTestingAdapter>
+  )
+  const { result } = renderHook(() => useAppsQueryState(), { wrapper })
+  return { result, onUrlUpdate }
+}
+
+// Groups scenarios for useAppsQueryState behavior.
+describe('useAppsQueryState', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  // Covers the hook return shape and default values.
+  describe('Initialization', () => {
+    it('should expose query and setQuery when initialized', () => {
+      const { result } = renderWithAdapter()
+
+      expect(result.current.query).toBeDefined()
+      expect(typeof result.current.setQuery).toBe('function')
+    })
+
+    it('should default to empty filters when search params are missing', () => {
+      const { result } = renderWithAdapter()
+
+      expect(result.current.query.tagIDs).toBeUndefined()
+      expect(result.current.query.keywords).toBeUndefined()
+      expect(result.current.query.isCreatedByMe).toBe(false)
+    })
+  })
+
+  // Covers parsing of existing URL search params.
+  describe('Parsing search params', () => {
+    it('should parse tagIDs when URL includes tagIDs', () => {
+      const { result } = renderWithAdapter('?tagIDs=tag1;tag2;tag3')
+
+      expect(result.current.query.tagIDs).toEqual(['tag1', 'tag2', 'tag3'])
+    })
+
+    it('should parse keywords when URL includes keywords', () => {
+      const { result } = renderWithAdapter('?keywords=search+term')
+
+      expect(result.current.query.keywords).toBe('search term')
+    })
+
+    it('should parse isCreatedByMe when URL includes true value', () => {
+      const { result } = renderWithAdapter('?isCreatedByMe=true')
+
+      expect(result.current.query.isCreatedByMe).toBe(true)
+    })
+
+    it('should parse all params when URL includes multiple filters', () => {
+      const { result } = renderWithAdapter(
+        '?tagIDs=tag1;tag2&keywords=test&isCreatedByMe=true',
+      )
+
+      expect(result.current.query.tagIDs).toEqual(['tag1', 'tag2'])
+      expect(result.current.query.keywords).toBe('test')
+      expect(result.current.query.isCreatedByMe).toBe(true)
+    })
+  })
+
+  // Covers updates driven by setQuery.
+  describe('Updating query state', () => {
+    it('should update keywords when setQuery receives keywords', () => {
+      const { result } = renderWithAdapter()
+
+      act(() => {
+        result.current.setQuery({ keywords: 'new search' })
+      })
+
+      expect(result.current.query.keywords).toBe('new search')
+    })
+
+    it('should update tagIDs when setQuery receives tagIDs', () => {
+      const { result } = renderWithAdapter()
+
+      act(() => {
+        result.current.setQuery({ tagIDs: ['tag1', 'tag2'] })
+      })
+
+      expect(result.current.query.tagIDs).toEqual(['tag1', 'tag2'])
+    })
+
+    it('should update isCreatedByMe when setQuery receives true', () => {
+      const { result } = renderWithAdapter()
+
+      act(() => {
+        result.current.setQuery({ isCreatedByMe: true })
+      })
+
+      expect(result.current.query.isCreatedByMe).toBe(true)
+    })
+
+    it('should support partial updates when setQuery uses callback', () => {
+      const { result } = renderWithAdapter()
+
+      act(() => {
+        result.current.setQuery({ keywords: 'initial' })
+      })
+
+      act(() => {
+        result.current.setQuery(prev => ({ ...prev, isCreatedByMe: true }))
+      })
+
+      expect(result.current.query.keywords).toBe('initial')
+      expect(result.current.query.isCreatedByMe).toBe(true)
+    })
+  })
+
+  // Covers URL updates triggered by query changes.
+  describe('URL synchronization', () => {
+    it('should sync keywords to URL when keywords change', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter()
+
+      act(() => {
+        result.current.setQuery({ keywords: 'search' })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.get('keywords')).toBe('search')
+      expect(update.options.history).toBe('push')
+    })
+
+    it('should sync tagIDs to URL when tagIDs change', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter()
+
+      act(() => {
+        result.current.setQuery({ tagIDs: ['tag1', 'tag2'] })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.get('tagIDs')).toBe('tag1;tag2')
+    })
+
+    it('should sync isCreatedByMe to URL when enabled', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter()
+
+      act(() => {
+        result.current.setQuery({ isCreatedByMe: true })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.get('isCreatedByMe')).toBe('true')
+    })
+
+    it('should remove keywords from URL when keywords are cleared', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter('?keywords=existing')
+
+      act(() => {
+        result.current.setQuery({ keywords: '' })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.has('keywords')).toBe(false)
+    })
+
+    it('should remove tagIDs from URL when tagIDs are empty', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter('?tagIDs=tag1;tag2')
+
+      act(() => {
+        result.current.setQuery({ tagIDs: [] })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.has('tagIDs')).toBe(false)
+    })
+
+    it('should remove isCreatedByMe from URL when disabled', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter('?isCreatedByMe=true')
+
+      act(() => {
+        result.current.setQuery({ isCreatedByMe: false })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.has('isCreatedByMe')).toBe(false)
+    })
+  })
+
+  // Covers decoding and empty values.
+  describe('Edge cases', () => {
+    it('should treat empty tagIDs as empty list when URL param is empty', () => {
+      const { result } = renderWithAdapter('?tagIDs=')
+
+      expect(result.current.query.tagIDs).toEqual([])
+    })
+
+    it('should treat empty keywords as undefined when URL param is empty', () => {
+      const { result } = renderWithAdapter('?keywords=')
+
+      expect(result.current.query.keywords).toBeUndefined()
+    })
+
+    it('should decode keywords with spaces when URL contains encoded spaces', () => {
+      const { result } = renderWithAdapter('?keywords=test+with+spaces')
+
+      expect(result.current.query.keywords).toBe('test with spaces')
+    })
+  })
+
+  // Covers multi-step updates that mimic real usage.
+  describe('Integration scenarios', () => {
+    it('should keep accumulated filters when updates are sequential', () => {
+      const { result } = renderWithAdapter()
+
+      act(() => {
+        result.current.setQuery({ keywords: 'first' })
+      })
+
+      act(() => {
+        result.current.setQuery(prev => ({ ...prev, tagIDs: ['tag1'] }))
+      })
+
+      act(() => {
+        result.current.setQuery(prev => ({ ...prev, isCreatedByMe: true }))
+      })
+
+      expect(result.current.query.keywords).toBe('first')
+      expect(result.current.query.tagIDs).toEqual(['tag1'])
+      expect(result.current.query.isCreatedByMe).toBe(true)
+    })
+  })
+})
@@ -1,6 +1,5 @@
-import type { ReadonlyURLSearchParams } from 'next/navigation'
-import { usePathname, useRouter, useSearchParams } from 'next/navigation'
-import { useCallback, useEffect, useMemo, useState } from 'react'
+import { parseAsArrayOf, parseAsBoolean, parseAsString, useQueryStates } from 'nuqs'
+import { useCallback, useMemo } from 'react'

 type AppsQuery = {
  tagIDs?: string[]
@@ -8,54 +7,51 @@ type AppsQuery = {
  isCreatedByMe?: boolean
 }

-// Parse the query parameters from the URL search string.
-function parseParams(params: ReadonlyURLSearchParams): AppsQuery {
-  const tagIDs = params.get('tagIDs')?.split(';')
-  const keywords = params.get('keywords') || undefined
-  const isCreatedByMe = params.get('isCreatedByMe') === 'true'
-  return { tagIDs, keywords, isCreatedByMe }
-}
-
-// Update the URL search string with the given query parameters.
-function updateSearchParams(query: AppsQuery, current: URLSearchParams) {
-  const { tagIDs, keywords, isCreatedByMe } = query || {}
-
-  if (tagIDs && tagIDs.length > 0)
-    current.set('tagIDs', tagIDs.join(';'))
-  else
-    current.delete('tagIDs')
-
-  if (keywords)
-    current.set('keywords', keywords)
-  else
-    current.delete('keywords')
-
-  if (isCreatedByMe)
-    current.set('isCreatedByMe', 'true')
-  else
-    current.delete('isCreatedByMe')
-}
+const normalizeKeywords = (value: string | null) => value || undefined

 function useAppsQueryState() {
-  const searchParams = useSearchParams()
-  const [query, setQuery] = useState<AppsQuery>(() => parseParams(searchParams))
+  const [urlQuery, setUrlQuery] = useQueryStates(
+    {
+      tagIDs: parseAsArrayOf(parseAsString, ';'),
+      keywords: parseAsString,
+      isCreatedByMe: parseAsBoolean,
+    },
+    {
+      history: 'push',
+    },
+  )

-  const router = useRouter()
-  const pathname = usePathname()
-  const syncSearchParams = useCallback((params: URLSearchParams) => {
-    const search = params.toString()
-    const query = search ? `?${search}` : ''
-    router.push(`${pathname}${query}`, { scroll: false })
-  }, [router, pathname])
+  const query = useMemo<AppsQuery>(() => ({
+    tagIDs: urlQuery.tagIDs ?? undefined,
+    keywords: normalizeKeywords(urlQuery.keywords),
+    isCreatedByMe: urlQuery.isCreatedByMe ?? false,
+  }), [urlQuery.isCreatedByMe, urlQuery.keywords, urlQuery.tagIDs])

-  // Update the URL search string whenever the query changes.
-  useEffect(() => {
-    const params = new URLSearchParams(searchParams)
-    updateSearchParams(query, params)
-    syncSearchParams(params)
-  }, [query, searchParams, syncSearchParams])
+  const setQuery = useCallback((next: AppsQuery | ((prev: AppsQuery) => AppsQuery)) => {
+    const buildPatch = (patch: AppsQuery) => {
+      const result: Partial<typeof urlQuery> = {}
+      if ('tagIDs' in patch)
+        result.tagIDs = patch.tagIDs && patch.tagIDs.length > 0 ? patch.tagIDs : null
+      if ('keywords' in patch)
+        result.keywords = patch.keywords ? patch.keywords : null
+      if ('isCreatedByMe' in patch)
+        result.isCreatedByMe = patch.isCreatedByMe ? true : null
+      return result
+    }

-  return useMemo(() => ({ query, setQuery }), [query])
+    if (typeof next === 'function') {
+      setUrlQuery(prev => buildPatch(next({
+        tagIDs: prev.tagIDs ?? undefined,
+        keywords: normalizeKeywords(prev.keywords),
+        isCreatedByMe: prev.isCreatedByMe ?? false,
+      })))
+      return
+    }
+
+    setUrlQuery(buildPatch(next))
+  }, [setUrlQuery])
+
+  return useMemo(() => ({ query, setQuery }), [query, setQuery])
 }

 export default useAppsQueryState
@@ -57,8 +57,13 @@ vi.mock('./hooks/use-dsl-drag-drop', () => ({
 }))

 const mockSetActiveTab = vi.fn()
-vi.mock('@/hooks/use-tab-searchparams', () => ({
-  useTabSearchParams: () => ['all', mockSetActiveTab],
+vi.mock('nuqs', () => ({
+  useQueryState: () => ['all', mockSetActiveTab],
+  parseAsString: {
+    withDefault: () => ({
+      withOptions: () => ({}),
+    }),
+  },
 }))

 // Mock service hooks - use object for mutable state (vi.mock is hoisted)
@@ -13,6 +13,7 @@ import dynamic from 'next/dynamic'
 import {
  useRouter,
 } from 'next/navigation'
+import { parseAsString, useQueryState } from 'nuqs'
 import { useCallback, useEffect, useRef, useState } from 'react'
 import { useTranslation } from 'react-i18next'
 import Input from '@/app/components/base/input'
@@ -24,7 +25,6 @@ import { NEED_REFRESH_APP_LIST_KEY } from '@/config'
 import { useAppContext } from '@/context/app-context'
 import { useGlobalPublicStore } from '@/context/global-public-context'
 import { CheckModal } from '@/hooks/use-pay'
-import { useTabSearchParams } from '@/hooks/use-tab-searchparams'
 import { useInfiniteAppList } from '@/service/use-apps'
 import { AppModeEnum } from '@/types/app'
 import AppCard from './app-card'
@@ -47,9 +47,10 @@ const List = () => {
  const router = useRouter()
  const { isCurrentWorkspaceEditor, isCurrentWorkspaceDatasetOperator } = useAppContext()
  const showTagManagementModal = useTagStore(s => s.showTagManagementModal)
-  const [activeTab, setActiveTab] = useTabSearchParams({
-    defaultTab: 'all',
-  })
+  const [activeTab, setActiveTab] = useQueryState(
+    'category',
+    parseAsString.withDefault('all').withOptions({ history: 'push' }),
+  )
  const { query: { tagIDs = [], keywords = '', isCreatedByMe: queryIsCreatedByMe = false }, setQuery } = useAppsQueryState()
  const [isCreatedByMe, setIsCreatedByMe] = useState(queryIsCreatedByMe)
  const [tagFilterValue, setTagFilterValue] = useState<string[]>(tagIDs)
@@ -16,8 +16,8 @@ let mockIsError = false
 const mockHandleImportDSL = vi.fn()
 const mockHandleImportDSLConfirm = vi.fn()

-vi.mock('@/hooks/use-tab-searchparams', () => ({
-  useTabSearchParams: () => [mockTabValue, mockSetTab],
+vi.mock('nuqs', () => ({
+  useQueryState: () => [mockTabValue, mockSetTab],
 }))

 vi.mock('ahooks', async () => {
@@ -3,6 +3,7 @@
 import type { CreateAppModalProps } from '@/app/components/explore/create-app-modal'
 import type { App } from '@/models/explore'
 import { useDebounceFn } from 'ahooks'
+import { useQueryState } from 'nuqs'
 import * as React from 'react'
 import { useCallback, useMemo, useState } from 'react'
 import { useTranslation } from 'react-i18next'
@@ -15,7 +16,6 @@ import Category from '@/app/components/explore/category'
 import CreateAppModal from '@/app/components/explore/create-app-modal'
 import ExploreContext from '@/context/explore-context'
 import { useImportDSL } from '@/hooks/use-import-dsl'
-import { useTabSearchParams } from '@/hooks/use-tab-searchparams'
 import {
  DSLImportMode,
 } from '@/models/app'
@@ -47,9 +47,8 @@ const Apps = ({
    handleSearch()
  }

-  const [currCategory, setCurrCategory] = useTabSearchParams({
-    defaultTab: allCategoriesEn,
-    disableSearchParams: false,
+  const [currCategory, setCurrCategory] = useQueryState('category', {
+    defaultValue: allCategoriesEn,
  })

  const {
@@ -22,6 +22,7 @@ import {
  createContext,
  useContextSelector,
 } from 'use-context-selector'
+import { useMarketplaceFilters } from '@/hooks/use-query-params'
 import { useInstalledPluginList } from '@/service/use-plugins'
 import {
  getValidCategoryKeys,
@@ -37,7 +38,6 @@ import { PLUGIN_TYPE_SEARCH_MAP } from './plugin-type-switch'
 import {
  getMarketplaceListCondition,
  getMarketplaceListFilterType,
-  updateSearchParams,
 } from './utils'

 export type MarketplaceContextValue = {
@@ -107,16 +107,22 @@ export const MarketplaceContextProvider = ({
  scrollContainerId,
  showSearchParams,
 }: MarketplaceContextProviderProps) => {
+  // Use nuqs hook for URL-based filter state
+  const [urlFilters, setUrlFilters] = useMarketplaceFilters()
+
  const { data, isSuccess } = useInstalledPluginList(!shouldExclude)
  const exclude = useMemo(() => {
    if (shouldExclude)
      return data?.plugins.map(plugin => plugin.plugin_id)
  }, [data?.plugins, shouldExclude])
-  const queryFromSearchParams = searchParams?.q || ''
-  const tagsFromSearchParams = searchParams?.tags ? getValidTagKeys(searchParams.tags.split(',')) : []
+
+  // Initialize from URL params (legacy support) or use nuqs state
+  const queryFromSearchParams = searchParams?.q || urlFilters.q
+  const tagsFromSearchParams = getValidTagKeys(urlFilters.tags)
  const hasValidTags = !!tagsFromSearchParams.length
-  const hasValidCategory = getValidCategoryKeys(searchParams?.category)
+  const hasValidCategory = getValidCategoryKeys(urlFilters.category)
  const categoryFromSearchParams = hasValidCategory || PLUGIN_TYPE_SEARCH_MAP.all
+
  const [searchPluginText, setSearchPluginText] = useState(queryFromSearchParams)
  const searchPluginTextRef = useRef(searchPluginText)
  const [filterPluginTags, setFilterPluginTags] = useState<string[]>(tagsFromSearchParams)
@@ -158,10 +164,6 @@ export const MarketplaceContextProvider = ({
        sortOrder: sortRef.current.sortOrder,
        type: getMarketplaceListFilterType(activePluginTypeRef.current),
      })
-      const url = new URL(window.location.href)
-      if (searchParams?.language)
-        url.searchParams.set('language', searchParams?.language)
-      history.replaceState({}, '', url)
    }
    else {
      if (shouldExclude && isSuccess) {
@@ -183,28 +185,32 @@ export const MarketplaceContextProvider = ({
    resetPlugins()
  }, [exclude, queryMarketplaceCollectionsAndPlugins, resetPlugins])

-  const debouncedUpdateSearchParams = useMemo(() => debounce(() => {
-    updateSearchParams({
-      query: searchPluginTextRef.current,
-      category: activePluginTypeRef.current,
-      tags: filterPluginTagsRef.current,
-    })
-  }, 500), [])
-
-  const handleUpdateSearchParams = useCallback((debounced?: boolean) => {
+  const applyUrlFilters = useCallback(() => {
    if (!showSearchParams)
      return
+    const nextFilters = {
+      q: searchPluginTextRef.current,
+      category: activePluginTypeRef.current,
+      tags: filterPluginTagsRef.current,
+    }
+    const categoryChanged = urlFilters.category !== nextFilters.category
+    setUrlFilters(nextFilters, {
+      history: categoryChanged ? 'push' : 'replace',
+    })
+  }, [setUrlFilters, showSearchParams, urlFilters.category])
+
+  const debouncedUpdateSearchParams = useMemo(() => debounce(() => {
+    applyUrlFilters()
+  }, 500), [applyUrlFilters])
+
+  const handleUpdateSearchParams = useCallback((debounced?: boolean) => {
    if (debounced) {
      debouncedUpdateSearchParams()
    }
    else {
-      updateSearchParams({
-        query: searchPluginTextRef.current,
-        category: activePluginTypeRef.current,
-        tags: filterPluginTagsRef.current,
-      })
+      applyUrlFilters()
    }
-  }, [debouncedUpdateSearchParams, showSearchParams])
+  }, [applyUrlFilters, debouncedUpdateSearchParams])

  const handleQueryPlugins = useCallback((debounced?: boolean) => {
    handleUpdateSearchParams(debounced)
@@ -84,12 +84,14 @@ const PluginTypeSwitch = ({
  const handlePopState = useCallback(() => {
    if (!showSearchParams)
      return
+    // nuqs handles popstate automatically
    const url = new URL(window.location.href)
    const category = url.searchParams.get('category') || PLUGIN_TYPE_SEARCH_MAP.all
    handleActivePluginTypeChange(category)
  }, [showSearchParams, handleActivePluginTypeChange])

  useEffect(() => {
+    // nuqs manages popstate internally, but we keep this for URL sync
    window.addEventListener('popstate', handlePopState)
    return () => {
      window.removeEventListener('popstate', handlePopState)
@@ -1,7 +1,6 @@
 import type {
  CollectionsAndPluginsSearchParams,
  MarketplaceCollection,
-  PluginsSearchParams,
 } from '@/app/components/plugins/marketplace/types'
 import type { Plugin } from '@/app/components/plugins/types'
 import { PluginCategoryEnum } from '@/app/components/plugins/types'
@@ -152,22 +151,3 @@ export const getMarketplaceListFilterType = (category: string) => {

  return 'plugin'
 }
-
-export const updateSearchParams = (pluginsSearchParams: PluginsSearchParams) => {
-  const { query, category, tags } = pluginsSearchParams
-  const url = new URL(window.location.href)
-  const categoryChanged = url.searchParams.get('category') !== category
-  if (query)
-    url.searchParams.set('q', query)
-  else
-    url.searchParams.delete('q')
-  if (category)
-    url.searchParams.set('category', category)
-  else
-    url.searchParams.delete('category')
-  if (tags && tags.length)
-    url.searchParams.set('tags', tags.join(','))
-  else
-    url.searchParams.delete('tags')
-  history[`${categoryChanged ? 'pushState' : 'replaceState'}`]({}, '', url)
-}
@@ -3,6 +3,7 @@
 import type { ReactNode, RefObject } from 'react'
 import type { FilterState } from './filter-management'
 import { noop } from 'es-toolkit/compat'
+import { useQueryState } from 'nuqs'
 import {
  useMemo,
  useRef,
@@ -13,7 +14,6 @@ import {
  useContextSelector,
 } from 'use-context-selector'
 import { useGlobalPublicStore } from '@/context/global-public-context'
-import { useTabSearchParams } from '@/hooks/use-tab-searchparams'
 import { PLUGIN_PAGE_TABS_MAP, usePluginPageTabs } from '../hooks'

 export type PluginPageContextValue = {
@@ -68,8 +68,8 @@ export const PluginPageContextProvider = ({
  const options = useMemo(() => {
    return enable_marketplace ? tabs : tabs.filter(tab => tab.value !== PLUGIN_PAGE_TABS_MAP.marketplace)
  }, [tabs, enable_marketplace])
-  const [activeTab, setActiveTab] = useTabSearchParams({
-    defaultTab: options[0].value,
+  const [activeTab, setActiveTab] = useQueryState('category', {
+    defaultValue: options[0].value,
  })

  return (
@@ -9,10 +9,6 @@ import {
 import { useBoolean } from 'ahooks'
 import { noop } from 'es-toolkit/compat'
 import Link from 'next/link'
-import {
-  useRouter,
-  useSearchParams,
-} from 'next/navigation'
 import { useEffect, useMemo, useState } from 'react'
 import { useTranslation } from 'react-i18next'
 import { useContext } from 'use-context-selector'
@@ -25,6 +21,7 @@ import { MARKETPLACE_API_PREFIX, SUPPORT_INSTALL_LOCAL_FILE_EXTENSIONS } from '@
 import { useGlobalPublicStore } from '@/context/global-public-context'
 import I18n from '@/context/i18n'
 import useDocumentTitle from '@/hooks/use-document-title'
+import { usePluginInstallation } from '@/hooks/use-query-params'
 import { fetchBundleInfoFromMarketPlace, fetchManifestFromMarketPlace } from '@/service/plugins'
 import { sleep } from '@/utils'
 import { cn } from '@/utils/classnames'
@@ -42,9 +39,6 @@ import PluginTasks from './plugin-tasks'
 import useReferenceSetting from './use-reference-setting'
 import { useUploader } from './use-uploader'

-const PACKAGE_IDS_KEY = 'package-ids'
-const BUNDLE_INFO_KEY = 'bundle-info'
-
 export type PluginPageProps = {
  plugins: React.ReactNode
  marketplace: React.ReactNode
@@ -55,33 +49,13 @@ const PluginPage = ({
 }: PluginPageProps) => {
  const { t } = useTranslation()
  const { locale } = useContext(I18n)
-  const searchParams = useSearchParams()
-  const { replace } = useRouter()
  useDocumentTitle(t('plugin.metadata.title'))

-  // just support install one package now
-  const packageId = useMemo(() => {
-    const idStrings = searchParams.get(PACKAGE_IDS_KEY)
-    try {
-      return idStrings ? JSON.parse(idStrings)[0] : ''
-    }
-    catch {
-      return ''
-    }
-  }, [searchParams])
+  // Use nuqs hook for installation state
+  const [{ packageId, bundleInfo }, setInstallState] = usePluginInstallation()

  const [uniqueIdentifier, setUniqueIdentifier] = useState<string | null>(null)
-
  const [dependencies, setDependencies] = useState<Dependency[]>([])
-  const bundleInfo = useMemo(() => {
-    const info = searchParams.get(BUNDLE_INFO_KEY)
-    try {
-      return info ? JSON.parse(info) : undefined
-    }
-    catch {
-      return undefined
-    }
-  }, [searchParams])

  const [isShowInstallFromMarketplace, {
    setTrue: showInstallFromMarketplace,
@@ -90,11 +64,9 @@ const PluginPage = ({

  const hideInstallFromMarketplace = () => {
    doHideInstallFromMarketplace()
-    const url = new URL(window.location.href)
-    url.searchParams.delete(PACKAGE_IDS_KEY)
-    url.searchParams.delete(BUNDLE_INFO_KEY)
-    replace(url.toString())
+    setInstallState(null)
  }
+
  const [manifest, setManifest] = useState<PluginDeclaration | PluginManifestInMarket | null>(null)

  useEffect(() => {
@@ -114,12 +86,17 @@ const PluginPage = ({
        return
      }
      if (bundleInfo) {
-        const { data } = await fetchBundleInfoFromMarketPlace(bundleInfo)
-        setDependencies(data.version.dependencies)
-        showInstallFromMarketplace()
+        try {
+          const { data } = await fetchBundleInfoFromMarketPlace(bundleInfo)
+          setDependencies(data.version.dependencies)
+          showInstallFromMarketplace()
+        }
+        catch (error) {
+          console.error('Failed to load bundle info:', error)
+        }
      }
    })()
-  }, [packageId, bundleInfo])
+  }, [packageId, bundleInfo, showInstallFromMarketplace])

  const {
    referenceSetting,
@@ -1,5 +1,6 @@
 'use client'
 import type { Collection } from './types'
+import { useQueryState } from 'nuqs'
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { useTranslation } from 'react-i18next'
 import Input from '@/app/components/base/input'
@@ -14,7 +15,6 @@ import CustomCreateCard from '@/app/components/tools/provider/custom-create-card
 import ProviderDetail from '@/app/components/tools/provider/detail'
 import WorkflowToolEmpty from '@/app/components/tools/provider/empty'
 import { useGlobalPublicStore } from '@/context/global-public-context'
-import { useTabSearchParams } from '@/hooks/use-tab-searchparams'
 import { useCheckInstalled, useInvalidateInstalledPluginList } from '@/service/use-plugins'
 import { useAllToolProviders } from '@/service/use-tools'
 import { cn } from '@/utils/classnames'
@@ -45,8 +45,8 @@ const ProviderList = () => {
  const { enable_marketplace } = useGlobalPublicStore(s => s.systemFeatures)
  const containerRef = useRef<HTMLDivElement>(null)

-  const [activeTab, setActiveTab] = useTabSearchParams({
-    defaultTab: 'builtin',
+  const [activeTab, setActiveTab] = useQueryState('category', {
+    defaultValue: 'builtin',
  })
  const options = [
    { value: 'builtin', text: t('tools.type.builtIn') },
@@ -1,4 +1,3 @@
 export const EDUCATION_VERIFY_URL_SEARCHPARAMS_ACTION = 'getEducationVerify'
 export const EDUCATION_VERIFYING_LOCALSTORAGE_ITEM = 'educationVerifying'
-export const EDUCATION_PRICING_SHOW_ACTION = 'educationPricing'
 export const EDUCATION_RE_VERIFY_ACTION = 'educationReVerify'
@@ -15,7 +15,6 @@ import { useModalContextSelector } from '@/context/modal-context'
 import { useProviderContext } from '@/context/provider-context'
 import { useEducationAutocomplete, useEducationVerify } from '@/service/use-education'
 import {
-  EDUCATION_PRICING_SHOW_ACTION,
  EDUCATION_RE_VERIFY_ACTION,
  EDUCATION_VERIFY_URL_SEARCHPARAMS_ACTION,
  EDUCATION_VERIFYING_LOCALSTORAGE_ITEM,
@@ -133,7 +132,6 @@ const useEducationReverifyNotice = ({

 export const useEducationInit = () => {
  const setShowAccountSettingModal = useModalContextSelector(s => s.setShowAccountSettingModal)
-  const setShowPricingModal = useModalContextSelector(s => s.setShowPricingModal)
  const setShowEducationExpireNoticeModal = useModalContextSelector(s => s.setShowEducationExpireNoticeModal)
  const educationVerifying = localStorage.getItem(EDUCATION_VERIFYING_LOCALSTORAGE_ITEM)
  const searchParams = useSearchParams()
@@ -160,8 +158,6 @@ export const useEducationInit = () => {
      if (educationVerifyAction === EDUCATION_VERIFY_URL_SEARCHPARAMS_ACTION)
        localStorage.setItem(EDUCATION_VERIFYING_LOCALSTORAGE_ITEM, 'yes')
    }
-    if (educationVerifyAction === EDUCATION_PRICING_SHOW_ACTION)
-      setShowPricingModal()
    if (educationVerifyAction === EDUCATION_RE_VERIFY_ACTION)
      handleVerify()
  }, [setShowAccountSettingModal, educationVerifying, educationVerifyAction])
@@ -1,6 +1,7 @@
 import type { Viewport } from 'next'
 import { ThemeProvider } from 'next-themes'
 import { Instrument_Serif } from 'next/font/google'
+import { NuqsAdapter } from 'nuqs/adapters/next/app'
 import GlobalPublicStoreProvider from '@/context/global-public-context'
 import { TanstackQueryInitializer } from '@/context/query-client'
 import { getLocaleOnServer } from '@/i18n-config/server'
@@ -97,17 +98,19 @@ const LocaleLayout = async ({
          disableTransitionOnChange
          enableColorScheme={false}
        >
-          <BrowserInitializer>
-            <SentryInitializer>
-              <TanstackQueryInitializer>
-                <I18nServer>
-                  <GlobalPublicStoreProvider>
-                    {children}
-                  </GlobalPublicStoreProvider>
-                </I18nServer>
-              </TanstackQueryInitializer>
-            </SentryInitializer>
-          </BrowserInitializer>
+          <NuqsAdapter>
+            <BrowserInitializer>
+              <SentryInitializer>
+                <TanstackQueryInitializer>
+                  <I18nServer>
+                    <GlobalPublicStoreProvider>
+                      {children}
+                    </GlobalPublicStoreProvider>
+                  </I18nServer>
+                </TanstackQueryInitializer>
+              </SentryInitializer>
+            </BrowserInitializer>
+          </NuqsAdapter>
        </ThemeProvider>
        <RoutePrefixHandle />
      </body>