feat: Add custom adapters API (unstable)

packages/docs/content/docs/adapters/onejs.mdx

@@ -14,10 +14,15 @@ core package.
 
 ## Step 1: Add the adapter code
 
-```tsx title="app/nuqs-adapter.tsx"
+<Callout type="warn">
+  The custom adapters APIs are not yet stable and may change in the future
+  in a minor or patch release (not following SemVer).
+</Callout>
+
+```tsx title="app/nuqs-one-adapter.tsx"
 import {
-  type AdapterOptions,
-  createAdapterProvider,
+  type unstable_AdapterOptions as AdapterOptions,
+  unstable_createAdapterProvider as createAdapterProvider,
   renderQueryString
 } from 'nuqs/adapters/custom'
 import { useActiveParams, useRouter } from 'one'
@@ -52,7 +57,7 @@ Integrate the adapter into the root layout file, by wrapping the `<Slot>`
 component:
 
 ```tsx title="app/_layout.tsx" /NuqsAdapter/
-import { NuqsAdapter } from './nuqs-adapter'
+import { NuqsAdapter } from './nuqs-one-adapter'
 import { Slot } from 'one'
 
 export default function Layout() {

packages/nuqs/adapters/custom.d.ts

@@ -0,0 +1,7 @@
+// This file is needed for projects that have `moduleResolution` set to `node`
+// in their tsconfig.json to be able to `import {} from 'nuqs/adapters/custom'`.
+// Other module resolutions strategies will look for the `exports` in `package.json`,
+// but with `node`, TypeScript will look for a .d.ts file with that name at the
+// root of the package.
+
+export * from '../dist/adapters/custom'

packages/nuqs/package.json

@@ -39,6 +39,7 @@
     "adapters/next/pages.d.ts",
     "adapters/remix.d.ts",
     "adapters/react-router.d.ts",
+    "adapters/custom.d.ts",
     "adapters/testing.d.ts"
   ],
   "type": "module",
@@ -78,6 +79,10 @@
       "types": "./dist/adapters/react-router.d.ts",
       "import": "./dist/adapters/react-router.js"
     },
+    "./adapters/custom": {
+      "types": "./dist/adapters/custom.d.ts",
+      "import": "./dist/adapters/custom.js"
+    },
     "./adapters/testing": {
       "types": "./dist/adapters/testing.d.ts",
       "import": "./dist/adapters/testing.js"

packages/nuqs/src/adapters/custom.ts

@@ -0,0 +1,11 @@
+export { renderQueryString } from '../url-encoding'
+export type {
+  AdapterInterface as unstable_AdapterInterface,
+  AdapterOptions as unstable_AdapterOptions,
+  UpdateUrlFunction as unstable_UpdateUrlFunction,
+  UseAdapterHook as unstable_UseAdapterHook
+} from './defs'
+export {
+  createAdapterProvider as unstable_createAdapterProvider,
+  type AdapterContext as unstable_AdapterContext
+} from './internal.context'

packages/nuqs/src/adapters/internal.context.ts

@@ -13,6 +13,14 @@ export const context = createContext<AdapterContext>({
 })
 context.displayName = 'NuqsAdapterContext'
 
+/**
+ * Create a custom adapter (context provider) for nuqs to work with your framework / router.
+ *
+ * Adapters are based on React Context,
+ *
+ * @param useAdapter
+ * @returns
+ */
 export function createAdapterProvider(useAdapter: UseAdapterHook) {
   return ({ children, ...props }: { children: ReactNode }) =>
     createElement(

packages/nuqs/tsup.config.ts

@@ -20,6 +20,7 @@ const entrypoints = {
     'adapters/next/pages': 'src/adapters/next/pages.ts',
     'adapters/remix': 'src/adapters/remix.ts',
     'adapters/react-router': 'src/adapters/react-router.ts',
+    'adapters/custom': 'src/adapters/custom.ts',
     'adapters/testing': 'src/adapters/testing.ts'
   },
   server: {