`nuqs/server` requires `react`

[boredland]

Context

What's your version of nuqs?

"nuqs": "^2.2.3",

What framework are you using?

• ✅ Next.js (pages router)

Which version of your framework are you using?

  next: 14.2.13 // An outdated version detected (latest is 15.1.0), upgrade is highly recommended!
  eslint-config-next: N/A
  react: 18.3.1
  react-dom: 18.3.1
  typescript: 5.6.3

Description

Apart from Frontend usage, I wanted to use my nuqs parsers to generate URLs on the server-side to be sent in emails.

For that I am trying to use a serializer on an API Route like so:

import {
  createSerializer,
  parseAsStringLiteral,
} from "nuqs/server";

export const universalQueryParams = {
  "user-menu": parseAsStringLiteral(["open", "closed"]).withDefault("closed"),
};

const serializer = createSerializer(universalQueryParams);

export const serializeUniversalQueryParams = serializer(base, values);

But sadly my Next.js-build fails, telling me:

[build:next] Failed to compile.
[build:next] 
[build:next] ./node_modules/nuqs/dist/server.js
[build:next] Attempted import error: 'cache' is not exported from 'react' (imported as 'cache').
[build:next] 
[build:next] Import trace for requested module:
[build:next] ./node_modules/nuqs/dist/server.js

Is there a trick to it? As I see it, this module is required for the cache feature, that I don't need. Would splitting up the path to allow direct imports of parsers/serializer help?

[franky47]

Yeah unfortunately the cache function didn't make the cut to React 19 (it's still in canary), so we might have to move that import to a dedicated one.

Since it's a breaking change, it's unlikely to happen soon though, but we could do it the other way around: provide imports for individual server-side features, like:

import { createSerializer } from 'nuqs/server/serializer'
import { parseAsStringLiteral } from 'nuqs/server/parsers'

What do you think?

[boredland]

That would be perfect for my use-case!

[franky47]

That solution I proposed has been implemented in #805, could you give it a go and let me know if it works please?

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

Note: those imports are temporary until v3 lands (no date planned at the moment). In v3, the cache will have been moved to it's own import (nuqs/server/cache), and the rest of server-side features (defs, parsers, serializer) will be available to import from nuqs/server in a framework-agnostic way.

[franky47]

@boredland I tested the imports and I'm seeing some issues with TypeScript not resolving the contents of nuqs/server/*, what's moduleResolution set to in your tsconfig.json?

[boredland]

Thank you for the super quick implementation! I didn't yet have the chance to test before my Christmas break, but will surely do it as the first thing next year!

[franky47]

Hey, happy new year!

Just as a heads-up, I've merged all the non-react-based exports under a single one, renamed to make it more obvious that it's temporary:

import { createSerializer, parseAsInteger, ... } from 'nuqs/server/temporary-react-agnostic'

It's available here:

pnpm add https://pkg.pr.new/nuqs@697736a31975c7696df524508629b4396e1e1d03