Add inertia community adapter docs

[Joehoel]

This PR adds documentation for a community adapter for Inertia.js. Inspired by the conversations on X. Related #786

[vercel]

@Joehoel is attempting to deploy a commit to the 47ng Team on Vercel.

A member of the Team first needs to authorize it.

[Joehoel]

Also might be related: inertiajs/inertia#2110

While creating the adapter I was facing some issues with persistent layouts from inertia and the state not updating correctly. Anyone face similar issues?

[franky47]

Echoing my inertiajs/inertia#2110 (comment), the key thing for adapters to work is that the searchParams value returned be reactive to URL changes, no matter where they originate from (nuqs itself, Link components, imperative router calls, calls to history.replaceState by 3rd party code etc).

This is unfortunately not an easy thing to do, and it looks like most adapters (apart from Next.js which does some of that for us) need to do the same kind of heavy lifting work to get this reactive value.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
nuqs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Nov 28, 2024 8:16pm

[Joehoel]

Thanks for clarifying. I can look into it when I have some extra time but if someone else wants to have a stab!

Maybe we can take some inspiration from the remix/react-router code for the reactive search params?

[franky47]

I have some updates for the Remix adapter that I need to test & push, it's adding a lot of those things I mentioned but it could probably be refactored to benefit a lot of other adapters. I might have more time to work on that next week.

[Joehoel]

Just realised Inertia has a usePage hook.

import { router, usePage } from "@inertiajs/react";
import {
  type unstable_AdapterOptions as AdapterOptions,
  unstable_createAdapterProvider as createAdapterProvider,
  renderQueryString,
} from "nuqs/adapters/custom";

function useNuqsInertiaAdapter() {
  const { searchParams } = new URL(location.origin + usePage().url);

  function updateUrl(search: URLSearchParams, options: AdapterOptions) {
    const url = new URL(location.href);
    url.search = renderQueryString(search);
    router.visit(url, {
      replace: options.history === "replace",
      preserveScroll: !options.scroll,
      preserveState: options.shallow,
    });
  }
  return {
    searchParams,
    updateUrl,
  };
}

export const NuqsAdapter = createAdapterProvider(useNuqsInertiaAdapter);

Implemented this is my test app and it works and fixes this issue inertiajs/inertia#2110 (comment)

[franky47]

Looks good! However I think the shallow option doesn't really map to Inertia's state preservation mechanism.

In nuqs, shallow: true (the default) means we should only update the client-side application when a search param changes (using the history API), and the server is not called. Setting shallow: false opts-in to calling the server for search params that do need to be read server-side.

The history API part is also something that could be factored out of all of those adapters.