feat: Allow server-side parser access

See #348.

README.md

@@ -139,6 +139,15 @@ export default () => {
 }
 ```
 
+### Using parsers in Server Components
+
+If you wish to parse the searchParams in server components, you'll need to
+import the parsers from `next-usequerystate/parsers`, which doesn't include
+the `"use client"` directive.
+
+See the [server-side parsing demo](./src/app/demos/server-side-parsing/) for
+an example.
+
 ## Default value
 
 When the query string is not present in the URL, the default behaviour is to

package.json

@@ -25,6 +25,7 @@
   },
   "files": [
     "dist/",
+    "parsers.d.ts",
     "useQueryState.gif"
   ],
   "type": "module",
@@ -37,11 +38,17 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs",
       "types": "./dist/index.d.ts"
+    },
+    "./parsers": {
+      "import": "./dist/parsers.js",
+      "require": "./dist/parsers.cjs",
+      "types": "./dist/parsers.d.ts"
     }
   },
   "tsup": {
     "entry": [
-      "src/lib/index.ts"
+      "src/lib/index.ts",
+      "src/lib/parsers.ts"
     ]
   },
   "scripts": {

parsers.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 'next-usequerystate/parsers'`.
+// 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/parsers'

src/app/demos/server-side-parsing/client.tsx

@@ -0,0 +1,54 @@
+'use client'
+
+import Link from 'next/link'
+import { parseAsBoolean, useQueryState } from '../../../../dist'
+import { counterParser } from './parser'
+
+type Props = {
+  serverSideCounter: number
+  children: React.ReactNode
+}
+
+export function ServerSideParsingDemoClient({
+  serverSideCounter,
+  children
+}: Props) {
+  const [shallow, setShallow] = useQueryState(
+    'shallow',
+    parseAsBoolean.withDefault(true)
+  )
+  const [counter, setCounter] = useQueryState('counter', {
+    ...counterParser,
+    shallow
+  })
+
+  return (
+    <main>
+      <Link href="/">⬅️ Home</Link>
+      <h1>Server side parsing</h1>
+      <div style={{ marginBottom: '1rem' }}>
+        <input
+          type="checkbox"
+          checked={shallow}
+          onChange={e => setShallow(e.target.checked)}
+          id="shallow"
+        />
+        <label htmlFor="shallow">Shallow?</label>
+      </div>
+      <button onClick={() => setCounter(x => x - 1)}>-</button>
+      <button onClick={() => setCounter(x => x + 1)}>+</button>
+      <button onClick={() => setCounter(null)}>Reset</button>
+      <p>Client side counter: {counter}</p>
+      <p>
+        Server side counter: {serverSideCounter} <em>(client-rendered)</em>
+      </p>
+      {children}
+      <p>
+        <em>
+          Check the server console, play with the "shallow" switch and try
+          refreshing the page.
+        </em>
+      </p>
+    </main>
+  )
+}

src/app/demos/server-side-parsing/page.tsx

@@ -0,0 +1,25 @@
+import { Suspense } from 'react'
+import { ServerSideParsingDemoClient } from './client'
+import { counterParser } from './parser'
+
+type PageProps = {
+  searchParams: {
+    counter?: string
+  }
+}
+
+export default function ServerSideParsingDemo({ searchParams }: PageProps) {
+  const counter =
+    counterParser.parse(searchParams.counter ?? '') ??
+    counterParser.defaultValue
+  console.log('Server side counter: %d', counter)
+  return (
+    <>
+      <Suspense>
+        <ServerSideParsingDemoClient serverSideCounter={counter}>
+          <p>Server rendered counter: {counter}</p>
+        </ServerSideParsingDemoClient>
+      </Suspense>
+    </>
+  )
+}

src/app/demos/server-side-parsing/parser.ts

@@ -0,0 +1,5 @@
+import { parseAsInteger } from '../../../../dist/parsers'
+
+export const counterParser = parseAsInteger
+  .withOptions({ shallow: false })
+  .withDefault(0)

src/app/page.tsx

@@ -1,6 +1,11 @@
 import Link from 'next/link'
 
-const demos = ['builder-pattern', 'subscribeToQueryUpdates', 'batching']
+const demos = [
+  'builder-pattern',
+  'subscribeToQueryUpdates',
+  'batching',
+  'server-side-parsing'
+]
 
 export default function IndexPage() {
   return (