feat: Add temporary dedicated server features imports

[franky47]

This allows using the serializer and the parsers (and later on the loaders) in server-side code without depending on React for the cache, as would be the case if importing from nuqs/server.

🦋 https://bsky.app/profile/francoisbest.com/post/3ld5bqxov722z
X: https://x.com/nuqs47ng/status/1867331081349083400

Tasks

• Update docs
• Move everything under a single path named explicitly (nuqs/server/temporary-react-agnostic or something)
• Rebase and include loaders
• Investigate import issues with moduleResolution -> try moving the export to nuqs/server-temporary-react-agnostic if it's a nesting issue.

Note

This PR adds three new imports:

• nuqs/server/cache: exports only the cache feature. Requires React canary (currently only useful in Next.js app router)
• nuqs/server/parsers: exports defs & all built-in parsers
• nuqs/server/serializer: exports defs & the createSerializer feature

The nuqs/server import is untouched in this PR.

Future breaking change plans

In nuqs v3:

• nuqs/server/cache will be the only way to import the cache feature, it will be removed from nuqs/server
• nuqs/server/parsers and nuqs/server/serializers may be removed for cleanup, as their code will be importable from nuqs/server in a framework-agnostic way.

Closes #804.
See also discussion #717.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
nuqs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Feb 19, 2025 8:35pm

[pkg-pr-new]

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

commit: f7a3217

[hauptrolle]

Any updates here? I cant import createLoader from nuqs/server with react 18 😭

[franky47]

@hauptrolle can you try the preview and let me know if it works for you?

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

import { createLoader } from 'nuqs/server/temporary-react-agnostic'

[hauptrolle]

@franky47 Wow, thank you for the fast response. Looks like the import is working, but typescript is complaining:
Cannot find module "nuqs/server/temporary-react-agnostic" or its corresponding type declarations.

[franky47]

Do you have a public repo I can take a look at? Or at least, the tsconfig.json, this is the last checkbox in the list for this issue.

[franky47]

If it's a mater of not being able to nest it under the nuqs/server prefix, maybe we could try nuqs/server-temporary-react-agnostic. 🙃

[hauptrolle]

The repo is work related so not public sorry ... My tsconfig looks like this:

{
  "include": ["env.d.ts", "**/*.ts", "**/*.tsx"],
  "compilerOptions": {
    "lib": ["DOM", "DOM.Iterable", "ES2022"],
    "types": ["@remix-run/node", "vite/client"],
    "rootDirs": ["."],
    "isolatedModules": true,
    "esModuleInterop": true,
    "jsx": "react-jsx",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "resolveJsonModule": true,
    "target": "ES2022",
    "strict": true,
    "allowJs": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "baseUrl": ".",
    "paths": {
      "~/*": ["./app/*"],
      "~e2e/*": ["./e2e-tests/*"],
    },
    "plugins": [
      {
        "name": "typescript-remix-routes-plugin"
      }
    ],

    // Vite takes care of building everything, not tsc.
    "noEmit": true
  }
}

[franky47]

Ah, if you're using Remix, you might as well import straight from nuqs:

import { createLoader } from 'nuqs'

This PR is mostly to bypass the import of cache from react used in the Next.js app router, when using shared code that doesn't end up in the app router tree (eg: API route handlers, or hybrid app/pages router setups).

Remix and other frameworks don't really care about the 'use client' directive injected at the top of the 'nuqs' import.

Also, you wouldn't need the preview PR version, importing loaders from nuqs is available since 2.3.0.

[hauptrolle]

Wow, thank you very much. I was following the example here where it looks like I have to import it from nuqs/server. It works now!

Thank you very much for this AWESOME package! <3

[franky47]

I'll update the docs to note the possible imports, thanks for the kind words!

[franky47]

@hauptrolle I know the import from nuqs was the immediate fix, but would you be able to try this please? I found another way (a really obvious one that I feel bad for not thinking about sooner) that could potentially solve the initial issue without requiring a dedicated export:

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

Then in your code, as it was initially:

import { createLoader, createSerializer, parseAsInteger /* etc..*/ } from 'nuqs/server' // Just to skip the "use client" directive

[franky47]

Closed in favour of #923.