Unnecessary 'use client' directive in Typescript declaration files

[Morabotti]

Description

Typescript definition files generated by nuqs include 'use client' directive, which cause typescript type error when running tsc. I don't see reason why this directive should be in the *.d.ts files. The problem can be fixed with "skipLibCheck": true option, but I would rather keep it as false.

Context

package.json:

{
  "name": "test",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "test": "tsc"
  },
  "keywords": [],
  "author": "",
  "license": "MIT",
  "description": "",
  "dependencies": {
    "nuqs": "^2.8.3",
    "react": "^19.2.1",
    "typescript": "^5.9.3"
  },
  "devDependencies": {
    "@types/react": "^19.2.7"
  }
}

tsconfig.json:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "lib": ["DOM", "DOM.Iterable", "ESNext"],
    "types": [],
    "jsx": "react",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "resolveJsonModule": true,
    "noEmit": true,
    "declaration": true,
    "declarationMap": true,
    "verbatimModuleSyntax": true,
    "isolatedDeclarations": true,
    "moduleDetection": "force",
    "downlevelIteration": true,
    "isolatedModules": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": false
  },
  "include": ["src/*.ts"],
  "exclude": ["node_modules"]
}

src/index.ts

import { useQueryState } from 'nuqs';
import { renderQueryString } from 'nuqs/adapters/custom';

Reproduction

1. Copy the minimal setup provided in context
2. Run npm run test
3. See error

Gotten error:

$ tsc
node_modules/nuqs/dist/adapters/custom.d.ts:1:1 - error TS1036: Statements are not allowed in ambient contexts.

1 'use client';
  ~~~~~~~~~~~~

node_modules/nuqs/dist/index.d.ts:1:1 - error TS1036: Statements are not allowed in ambient contexts.

1 'use client';
  ~~~~~~~~~~~~


Found 2 errors in 2 files.

Errors  Files
     1  node_modules/nuqs/dist/adapters/custom.d.ts:1
     1  node_modules/nuqs/dist/index.d.ts:1

[franky47]

That makes sense, thanks for the report (I always have skipLibCheck enabled).

Would you like to open a PR? IIRC, the directive is injected in the tsdown post build callback in runtime files, but if it's added by default by .d.ts bundling, that would also be a good place to strip it from type definition outputs.

[Morabotti]

Thanks for the hint. I think you are right. I tried to build the project earlier to debug the issue but stopped after having some problems with Turbo and Windows specific stuff. I will try again later and fix it.

[franky47]

Thanks for the PR! Could you try the preview build and let me know if it fixes the problem please?

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

Also, what were your issues on Windows if you don't mind me asking?

[Morabotti]

This preview build works good.

Windows related "issue" was because of pnpm build failed. This failed because of package/nuqs prebuild step relies on rm which is not a Windows native command. This and unfamilarity with Turborepo caused the initial issue.

You could include rimraf as dev dependency and use it instead to make it not os-specific.

[franky47]

Thanks for the feedback, that prebuild script isn't even needed since tsdown has the clean option to do that too, that must have been a leftover thing from a previous build setup, I'll remove it.

[github-actions]

🎉 This issue has been resolved in version 2.8.4 🎉

The release is available on:

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

Your semantic-release bot 📦🚀