Implement shadcn registry

[franky47]

Discussed in #916

^{Originally posted by junwen-k February 13, 2025}
We could potentially leverage shadcn's new custom registry support for a seamless community parsers installation process. I ran a quick test, and it seems to work:

registry.json

{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "nuqs",
  "homepage": "https://nuqs.47ng.com",
  "items": [
    {
      "name": "use-pagination-search-params",
      "type": "registry:hook",
      "title": "usePaginationSearchParams",
      "description": "A hook to use pagination search params.",
      "dependencies": ["nuqs"],
      "files": [
        {
          "path": "registry/hooks/use-pagination-search-params.ts",
          "type": "registry:hook"
        }
      ]
    }
  ]
}

registry/hooks/use-pagination-search-params.ts

import { createParser, parseAsInteger, useQueryStates } from "nuqs";

// Page index is zero-indexed internally but one-indexed in the URL
// to align with UI expectations.
const pageIndexParser = createParser({
  parse: (query) => {
    const page = parseAsInteger.parse(query);
    return page === null ? null : page - 1;
  },
  serialize: (value) => parseAsInteger.serialize(value + 1),
});

const paginationParsers = {
  pageIndex: pageIndexParser.withDefault(0),
  pageSize: parseAsInteger.withDefault(10),
};

const paginationUrlKeys = {
  pageIndex: "page",
  pageSize: "perPage",
};

export function usePaginationSearchParams() {
  return useQueryStates(paginationParsers, { urlKeys: paginationUrlKeys });
}

Installation

Following the shadcn setup guide, after running:

shadcn build

We get the registry output. Now, assuming this is hosted at https://nuqs.47ng.com/r/use-pagination-search-params.json, we can seamlessly install the hook with:

pnpm dlx shadcn@latest add https://nuqs.47ng.com/r/use-pagination-search-params.json

This might however require users to have the components.json in order for it to work though, but it's worth exploring!

Scoped & trusted registries

This could cleanup the CLI even further, and not require users to have to touch their components.json file (if they even have one):

npx shadcn add @nuqs/pagination
npx shadcn add @nuqs/adapters/waku
npx shadcn add @nuqs/adapters/inertia
npx shadcn add @nuqs/helpers/zod-codecs
npx shadcn add @nuqs/helpers/nextjs-typed-routes

https://x.com/theorcdev/status/1963520008706769062

https://shadcnregistry.com/hookas

[I-3B]

i tried to replicate this example locally in one of my projects (that doesn't have an existing components.json nor tailwindcss)
getting this error:

pnpm dlx shadcn@latest add http://localhost:3000/r/use-pagination-search-params.json                   
✔ You need to create a components.json file to add components. Proceed? … yes

No Tailwind CSS configuration found at /***/***/***
It is likely you do not have Tailwind CSS installed or have an invalid configuration.
Install Tailwind CSS then try again.
Visit https://tailwindcss.com/docs/guides/nextjs to get started.

I'm not sure if this limitation is avoidable, but should take this into account.

[franky47]

From shadcn on Twitter, about declaring a registry without a Tailwind dependency:

It’s there. If you use type:registry:file, it skips framework detection.
See Universal Items

https://ui.shadcn.com/docs/registry/examples#universal-items

[I-3B]

cool!
you can assign this to me if it's not already in progress

next step would be to create the registy package packages/registry or include it directly in docs package under /r/
lemme know what approach is preferable

also will include in it parseAsTuple for starter, as I'm not aware of the other possible parsers/adapters to add

[franky47]

next step would be to create the registy package packages/registry or include it directly in docs package under /r/
lemme know what approach is preferable

One thing I'd love is for whatever is shipping via the registry to be:

1. Tested — unit for parsers, somewhat e2e for adapters (maybe via external repos to avoid pulling a ton of extra deps into the main lockfile? Eg: https://github.com/47ng/nuqs-inertia-pingcrm)
2. Available as both copy/paste sources & copy shadcn CLI command in the docs

For point 1, a separate package might make sense (to isolate the testing rigs from the docs), with the docs pulling it as a dependency and importing something that outputs the final format.

For point 2, is it a spec requirement to have the /r/ prefix? For the manifest I don't really mind, I'd like folks to be able to install things like:

$ npx shadcn@latest add @nuqs/parseAsTuple

I was chatting with @TheOrcDev who's 8bitcn uses the registry a lot, about possibly adding search params and SSR'd codegen for customisation 👀

Imagine (for a CLI-driven version of https://nuqs.dev/docs/parsers/community/tanstack-table#pagination):

$ npx shadcn@latest add @nuqs/tanstack-table/pagination?pageKey=p&sizeKey=size

That's way more advanced though, it's likely people wouldn't go that far into customising a one-time CLI command when they can trivially tweak the output.