Add support for other routers

[vanenshi]

Hi everyone
I forked this library and changed the router from NextJs to react-router, and it worked perfectly
I was thinking about an architecture change to add support for each router by using an extension. this way community can also help by adding support for more router libraries

[franky47]

Hi Amir, thanks for opening this discussion.

Do you have a link to your implementation with react-router?

One thing I'd love to be able to do eventually, is for the nuqs package to work universally across React apps, no matter what meta-framework is used additionally.

A non-exhaustive list of such frameworks would be:

• Vanilla React (SPA, no router)
• Next.js (what nuqs currently does)
• Next.js with wrapped routers (see Shallow routing on Next.js 13's next/navigation vercel/next.js#48110 (reply in thread))
• Remix / react-router v7
• React Router v5 & v6
• TanStack Router / Start
• Inertia
• Waku
• Storybook
• Gatsby
• (feel free to reply to this message to suggest others)

One way to do this could be to provide the implementation (interfaces with each framework/router's APIs) via Context, but this introduces an additional step to integrate nuqs, and nuqs-aware components. Ideally, an automatic way that doesn't break locality of behaviour would be best: at import time, the correct implementation is selected and loaded. This shifts the problem/burden onto bundlers, which would add another additional level of complexity.

Another issue is the options: some of them make sense in the context of a full-stack app with a server ready to receive updated search params in a request, and render an updated view. But most traditional React apps are SPAs without any form of SSR or BFF. This raises the question of what to do with the shallow prop (directly mirrored from the Next.js router API) in those contexts: if a nuqs-aware component intended to notify a server is used in a SPA, what should happen?

[franky47]

A couple of thoughts about this:

Using Context to provide two things:

• A hook that returns URLSearchParams, reacting to changes in the URL. Trivial wrapper around useSearchParams in both Next.js and Remix/RR, but will require patching the history methods in vanilla React, as the popstate event doesn't fire on shallow updates (only on fwd/back navigation).
• A method to update the URL with options. This one might lead to leaky abstractions as Next.js is kind of picky on what URLs we can feed it, and it depends on configuration (pages vs app router, basePath or not etc).

How we choose what to put in this Context is the key to a good DX here. Having every user needing to wrap their app in a context provider in a top-level client component is not great, especially since the hooks have worked without one since the beginning.

This leads to a bundling question: how does a Next.js app know to only bundle the Context adapter for Next.js, and not the vanilla/Remix/RR ones? And vice versa.

Ultimately, the idea of having components publishable on NPM that use nuqs in a universal way might be difficult to do in practice, in terms of peer dependencies. The shadcn/ui copy-paste approach works better in this case (maybe one nuqs import to update to switch from the Next.js implementation to the Remix one).

[Talent30]

Brilliant idea

[franky47]

Status update: I've started tinkering with this idea of "adapters" to support other routers & frameworks.

An adapter is a hook that returns:

• The current search params (an URLSearchParams instance to make it standards-based), in a reactive way (ie: when they change, the hook should re-run and return the updated search params).
• A function to update the URL, given:
  • The URLSearchParams to apply
  • A subset of nuqs Options (shallow | history | scroll)

Each framework-specific implementation can then implement that hook (by calling framework-specific hooks) and expose a Context provider to pass it down. You'd wrap your app with it, and all useQueryState(s) hooks are now connected to your framework, no changes necessary in the components.

The major drawback is that this Context provider is now required, and cannot be defaulting to Next.js because of bundling issues in other frameworks. I would have loved to have a progressive adoption path, I might keep tinkering in this direction.

But one great side-effect / advantage is that it becomes easy to provide a mock adapter for unit tests, addressing concerns raised in #259. Here's what a unit test could look like:

import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { NuqsTestingAdapter, type UrlUpdateEvent } from 'nuqs/adapters/testing'
import { describe, expect, it, vi } from 'vitest'
import { CounterButton } from './counter-button'

it('should increment the count when clicked', async () => {
  const user = userEvent.setup()
  const onUrlUpdate = vi.fn<[UrlUpdateEvent]>()
  render(<CounterButton />, {
    // Setup the test by passing initial search params / querystring:
    wrapper: ({ children }) => (
      <NuqsTestingAdapter searchParams="?count=42" onUrlUpdate={onUrlUpdate}>
        {children}
      </NuqsTestingAdapter>
    )
  })
  // Act
  const button = screen.getByRole('button')
  await user.click(button)
  // Assert changes in the state and in the (mocked) URL
  expect(button).toHaveTextContent('count is 43')
  expect(onUrlUpdate).toHaveBeenCalledOnce()
  expect(onUrlUpdate.mock.calls[0][0].queryString).toBe('?count=43')
  expect(onUrlUpdate.mock.calls[0][0].searchParams.get('count')).toBe('43')
  expect(onUrlUpdate.mock.calls[0][0].options.history).toBe('push')
})

[franky47]

I have opened a draft PR implementing adapters in #644. You can try a preview here (here be dragons):

pnpm add https://pkg.pr.new/nuqs@644

You'll need to wrap your application in a NuqsAdapter, as such:

Vanilla React (eg: with Vite):

import { NuqsAdapter } from 'nuqs/adapters/react'

createRoot(document.getElementById('root')!).render(
  <NuqsAdapter>
    <App />
  </NuqsAdapter>
)

Next.js, app router:

// src/app/layout.tsx
import { NuqsAdapter } from 'nuqs/adapters/next'
import { type ReactNode } from 'react'

export default function RootLayout({
  children
}: {
  children: ReactNode
}) {
  return (
    <html>
      <body>
        <NuqsAdapter>{children}</NuqsAdapter>
      </body>
    </html>
  )
}

Next.js, pages router:

// src/pages/_app.tsx
import type { AppProps } from 'next/app'
import { NuqsAdapter } from 'nuqs/adapters/next'

export default function MyApp({ Component, pageProps }: AppProps) {
  return (
    <NuqsAdapter>
      <Component {...pageProps} />
    </NuqsAdapter>
  )
}

More adapters will come soon, I'd say Remix / React Router should be next.

I don't think supporting TanStack Router/Start is very useful, since the type-safe handling of search params and association with routes there is miles better than what nuqs can provide.

[vanenshi]

Thanks @franky47, this looks great 👍.
but how will we change the Adapter from next to the other routers? For example, you can rename this adapter from NuqsAdapter to NextAdapter to indicate which router this adapter supports

[franky47]

The naming of the adapters is still up for debate, it looks like people preferred the same name for all (because you're only going to use one in the end):
https://x.com/fortysevenfx/status/1836426286790578420

But this may be confusing, since you have to look up the import to know which adapter you're using (also auto-imports might have a hard time with it).

[EfstathiadisD]

I have one question on this. Why is it important to rely on specific routers? I mean, why can't we use Browser APIs? Even server wise just parsing the URL doesn't require specific knowledge as far as I understand.. Correct me if I am wrong.

I would point to a future where frameworks are just an abstraction and not the end all be all. Why do we need specific useParams for each framework? Isn't nuqs capable of reading/parsing/encoding the url itself with standard browser apis?

Even if some func, needed to be abstracted a Proxy is more than enough to handle that specific scenario. Would love to discuss this. WDYT?

[franky47]

Frameworks (particularly SSR ones like Remix & Next.js) don't always expose the URL in the render lifecycle, but they do provide APIs to access it, which are consistent between server-side rendering and hydration on the client. Without this, you would get hydration errors, or a flash of invalid values.

By contrast, the React adapter (which targets SPAs running only on the client, no SSR/SSG) makes direct use of browser APIs (reading from location.search and writing to window.history).

[Thomas-Vos00]

For people visiting this forum for an inertia adapter, here is some quick hacky solution I made, it seems to work fine.

import { router } from '@inertiajs/core';
import { startTransition, useCallback, useEffect, useState } from 'react';
import mitt, { Emitter } from 'mitt';
import {
  renderQueryString,
  unstable_AdapterInterface,
  unstable_AdapterOptions,
  unstable_createAdapterProvider,
} from 'nuqs/adapters/custom';

export type SearchParamsSyncEmitter = Emitter<{ update: URLSearchParams }>;

const emitter: SearchParamsSyncEmitter = mitt();

function useNuqsInertiaAdapter(): unstable_AdapterInterface {
  const [searchParams, setSearchParams] = useState(() => {
    if (typeof location === 'undefined') {
      return new URLSearchParams();
    }
    return new URLSearchParams(location.search);
  });

  const updateUrl = useCallback(
    (search: URLSearchParams, options: Required<unstable_AdapterOptions>) => {
      startTransition(() => {
        const url = new URL(location.href);
        url.search = renderQueryString(search);

        emitter.emit('update', search);

        if (!options.shallow) {
          const visitOptions = {
            preserveScroll: !options.scroll,
            preserveState: true,
            replace: options.history === 'replace',
          };

          router.visit(url.pathname + url.search, visitOptions);
        }
      });
    },
    [],
  );

  useEffect(() => {
    function onPopState() {
      setSearchParams(new URLSearchParams(location.search));
    }

    function onEmitterUpdate(search: URLSearchParams) {
      setSearchParams(search);
    }

    emitter.on('update', onEmitterUpdate);
    window.addEventListener('popstate', onPopState);

    return () => {
      emitter.off('update', onEmitterUpdate);
      window.removeEventListener('popstate', onPopState);
    };
  }, []);

  return {
    searchParams,
    updateUrl,
    rateLimitFactor: 1,
  };
}

export const NuqsAdapter = unstable_createAdapterProvider(
  useNuqsInertiaAdapter,
);

// /**
// I haven't tested this
// export function enableHistorySync() {
//   patchHistory(emitter, 'inertia');
// }

[franky47]

Thanks! See also #786 for Inertia-related adapter discussion.