doc: Add new path for the cache feature

Author: franky47

README.md

@@ -634,12 +634,9 @@ to do so in a type-safe manner.
 
 ```tsx
 // searchParams.ts
-import {
-  createSearchParamsCache,
-  parseAsInteger,
-  parseAsString
-} from 'nuqs/server'
-// Note: import from 'nuqs/server' to avoid the "use client" directive
+import { createSearchParamsCache } from 'nuqs/server/cache'
+import { parseAsInteger, parseAsString } from 'nuqs/server'
+// Note: import parsers from 'nuqs/server' to avoid the "use client" directive
 
 export const searchParamsCache = createSearchParamsCache({
   // List your search param keys and associated parsers here:
@@ -681,7 +678,8 @@ parser declaration with `useQueryStates` for type-safety in client components:
 
 ```tsx
 // searchParams.ts
-import { parseAsFloat, createSearchParamsCache } from 'nuqs/server'
+import { parseAsFloat } from 'nuqs/server'
+import { createSearchParamsCache } from 'nuqs/server/cache'
 
 export const coordinatesParsers = {
   lat: parseAsFloat.withDefault(45.18),

errors/NUQS-500.md

@@ -22,12 +22,8 @@ Run the `parse` method and feed it the page's `searchParams`:
 
 ```tsx
 // page.tsx
-import {
-  createSearchParamsCache,
-  parseAsInteger,
-  parseAsString,
-  type SearchParams
-} from 'nuqs/server'
+import { parseAsInteger, parseAsString, type SearchParams } from 'nuqs/server'
+import { createSearchParamsCache } from 'nuqs/server/cache'
 
 const cache = createSearchParamsCache({
   q: parseAsString,

packages/docs/content/docs/server-side.mdx

@@ -4,7 +4,7 @@ description: Type-safe search params on the server
 ---
 
 <Callout>
-  This feature is available for Next.js only.
+  The `next/server/cache` feature is available for Next.js app router only.
 </Callout>
 
 If you wish to access the searchParams in a deeply nested Server Component
@@ -20,12 +20,9 @@ to do so in a type-safe manner.
 </Callout>
 
 ```ts title="searchParams.ts"
-import {
-  createSearchParamsCache,
-  parseAsInteger,
-  parseAsString
-} from 'nuqs/server'
-// Note: import from 'nuqs/server' to avoid the "use client" directive
+import { createSearchParamsCache } from 'nuqs/server/cache'
+import { parseAsInteger, parseAsString } from 'nuqs/server'
+// Note: import parsers from 'nuqs/server' to avoid the "use client" directive
 
 export const searchParamsCache = createSearchParamsCache({
   // List your search param keys and associated parsers here:
@@ -61,17 +58,24 @@ function Results() {
 }
 ```
 
+<Callout type="warn" title="Deprecation notice">
+  The cache feature is also accessible from `nuqs/server` in nuqs@^2, but
+  will be removed from that import in nuqs@3.0.0.
+  Please update your imports to `nuqs/server/cache` for a smoother transition.
+
+  This is to allow non-Next.js server code to use the `nuqs/server` import
+  without having to install React canary for the `cache` function.
+</Callout>
+
 The cache will only be valid for the current page render
 (see React's [`cache`](https://react.dev/reference/react/cache) function).
 
 Note: the cache only works for **server components**, but you may share your
 parser declaration with `useQueryStates` for type-safety in client components:
 
 ```ts title="searchParams.ts"
-import {
-  parseAsFloat,
-  createSearchParamsCache
-} from 'nuqs/server'
+import { parseAsFloat } from 'nuqs/server'
+import { createSearchParamsCache } from 'nuqs/server/cache'
 
 export const coordinatesParsers = {
   lat: parseAsFloat.withDefault(45.18),

packages/docs/src/app/(pages)/stats/searchParams.ts

@@ -1,4 +1,5 @@
-import { createSearchParamsCache, parseAsStringLiteral } from 'nuqs/server'
+import { parseAsStringLiteral } from 'nuqs/server'
+import { createSearchParamsCache } from 'nuqs/server/cache'
 
 export const pkgOptions = ['nuqs', 'next-usequerystate', 'both'] as const
 export const pkgParser = parseAsStringLiteral(pkgOptions).withDefault('both')

packages/docs/src/app/playground/(demos)/pagination/searchParams.ts

@@ -1,9 +1,9 @@
 import {
-  createSearchParamsCache,
   createSerializer,
   parseAsInteger,
   parseAsStringLiteral
 } from 'nuqs/server'
+import { createSearchParamsCache } from 'nuqs/server/cache'
 
 export const renderingOptions = ['server', 'client'] as const
 export type RenderingOptions = (typeof renderingOptions)[number]

packages/e2e/next/src/app/app/cache/searchParams.ts

@@ -1,9 +1,5 @@
-import {
-  createSearchParamsCache,
-  parseAsBoolean,
-  parseAsInteger,
-  parseAsString
-} from 'nuqs/server'
+import { parseAsBoolean, parseAsInteger, parseAsString } from 'nuqs/server'
+import { createSearchParamsCache } from 'nuqs/server/cache'
 
 export const parsers = {
   str: parseAsString,

packages/e2e/next/src/app/app/push/searchParams.ts

@@ -1,4 +1,5 @@
-import { createSearchParamsCache, parseAsInteger } from 'nuqs/server'
+import { parseAsInteger } from 'nuqs/server'
+import { createSearchParamsCache } from 'nuqs/server/cache'
 
 export const parser = parseAsInteger.withDefault(0).withOptions({
   history: 'push'

packages/e2e/next/src/app/app/rewrites/destination/searchParams.ts

@@ -1,4 +1,5 @@
-import { createSearchParamsCache, parseAsString } from 'nuqs/server'
+import { parseAsString } from 'nuqs/server'
+import { createSearchParamsCache } from 'nuqs/server/cache'
 
 export const searchParams = {
   injected: parseAsString.withDefault('null'),

packages/nuqs/src/index.server.ts

@@ -1,3 +1,9 @@
+/** @deprecated Import createSearchParamsCache from 'nuqs/server/cache' instead.
+ *
+ * This export will be removed from 'nuqs/server' in nuqs@3.0.0,
+ * to allow non-Next.js server code to use the parsers, serializeres and other
+ * server-side utilities without depending on React canary for the `cache` function.
+ */
 export { createSearchParamsCache } from './cache'
 export type { HistoryOptions, Nullable, Options, SearchParams } from './defs'
 export * from './parsers'

packages/nuqs/src/tests/cache.test-d.ts

@@ -1,10 +1,10 @@
 import { expectError, expectNotAssignable, expectType } from 'tsd'
 import {
-  createSearchParamsCache,
   parseAsBoolean,
   parseAsInteger,
   parseAsString
 } from '../../dist/server'
+import { createSearchParamsCache } from '../../dist/server/cache'
 
 {
   const cache = createSearchParamsCache({