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

[franky47]

Hey y'all, if the dependency on React is not an issue (this package is, after all, a library for React), but the cache is (eg: using React 18 or 19 but not a canary version that includes it), I have a possible fix to import from nuqs/server (without needing a new export):

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

Then in your code, as it was initially:

// Import from 'nuqs/server' to skip the "use client" directive in Next.js app router server code.
// Note: other frameworks don't need this and can import straight from 'nuqs'.
import { createLoader, createSerializer, parseAsInteger /* etc..*/ } from 'nuqs/server'

This doesn't solve wanting to, say, parse search params in an isolated, React-free JS backend web framework (like Fastify, Hono, Express etc), but I feel like this kind of use-case might be a tangent that #805 could focus on, rather than requiring everyone else to rewrite their imports.

[alylim]

I'm trying to run some tests in nextjs14 using vitest, I've tried the latest fix

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

but am getting an error from

import { createSearchParamsCache } from "nuqs/server"

> TypeError: React.cache is not a function

[franky47]

@alylim thanks for the feedback, you'll need to mock that cache function in tests, as even if you can import it (using React canary), I doubt it would behave the right way in a testing environment. Here's how I did it on my end, let me know if it works for you:

nuqs/packages/nuqs/src/cache.test.ts

Lines 6 to 17 in da5ee6c

	vi.mock('react', () => {
	return {
	cache<T, CachedFunction extends () => T>(fn: CachedFunction) {
	let cache: T | undefined = undefined
	function cachedFn() {
	cache ??= fn()
	return cache
	}
	return cachedFn
	}
	}
	})

[alylim]

@franky47 Appreciate the quick response! It still does not work on my end but I reckon it's probably something to do with how I've implemented the tests rather than an issue with nuqs.

[franky47]

@alylim if the issue isn't related to the cache import not being found, feel free to open a dedicated issue or discussion with more details.

[github-actions]

🎉 This issue has been resolved in version 2.4.1 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀