Docs for updating custom registries?

[jkinley]

Thanks for all the amazing updates. The new CLI features are amazing. One thing that is confusing though is how to keep our current custom registry up to date with everything. We obviously do not want our custom registry using old defaults like "new-york" and such. this means making our custom registry more aligned with new CLI. How to do this? Basic migration guide? How to covert legacy custom registry into preset? It would really be helpful to provide some guidance here as we were early adopters and we don't want to be left behind.

[BitWise-0x]

There's no official migration guide for custom registries yet, but I've been through this myself. Here's what you need to do:

1. Update your registry item schema

Make sure every item in your registry.json references the current schema:

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "my-component",
  "type": "registry:ui",
  ...
}

The old type values are gone — use registry:ui, registry:component, registry:block, etc.

2. Drop the "style": "new-york" field

The legacy style field with values like "new-york" or "default" is replaced. The current system uses named styles like nova, vega, maia, lyra, mira. But you probably don't need to set a style at all unless you're distributing a full design system.

3. If you're distributing a full design system, use registry:base

A registry:base item carries a config field that tells the CLI what style, icon library, base color, etc. to use:

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "my-preset",
  "type": "registry:base",
  "config": {
    "style": "nova",
    "iconLibrary": "lucide",
    "tailwind": {
      "baseColor": "zinc"
    }
  }
}

4. If you extend shadcn defaults, use registry:style

A registry:style item inherits from shadcn by default. If you want a fully independent design system, set "extends": "none". Otherwise it merges on top of the default styles.

5. Migrate CSS variables to the new format

The cssVars field now supports three scopes: theme, light, and dark. For Tailwind v4 projects, theme-level variables go under cssVars.theme (the old tailwind config field is deprecated for v4):

{
  "cssVars": {
    "theme": {
      "--radius": "0.5rem",
      "--font-sans": "Inter, sans-serif"
    },
    "light": {
      "--background": "0 0% 100%",
      "--foreground": "0 0% 3.9%"
    },
    "dark": {
      "--background": "0 0% 3.9%",
      "--foreground": "0 0% 98%"
    }
  }
}

6. Consumer-side: namespaced registries

Your users configure their components.json to point at your registry:

{
  "registries": {
    "@acme": "https://your-registry.com/r/{name}.json"
  }
}

The URL supports {name} and {style} placeholders. They install with npx shadcn add @acme/component-name.

7. Build your registry output

Run shadcn build to generate the JSON files from your registry.json. This validates everything against the current schema.

---

Presets (the encoded config strings like nova, vega, etc.) are a CLI init-time concept — your custom registry doesn't need to become a preset. Just make sure your items use the current schema and types, and you're good.

Hope this helps — I agree some official docs on this migration path would be really valuable.

[jkinley]

it could be good to be able to support custom presets too. you could have one for marketing and engineering. for example. yeah, I think I am going to have to setup a demo that i can share to get feedback on. I really think shad needs to have a roadmap on the docs so that we can be prepared for these changes.

[jkinley]

Did you put your registry:base item in you main registry.json? Were you able to link to it so you could use it as a preset? I see that now all the items get a schema too, but when you look at shad's /public/r/ they are not in there:

https://github.com/shadcn-ui/ui/blob/main/apps/v4/registry.json

This is really confusing to understand without docs.

P.S. Do you have a live registry that you are sharing? I'd love to see if you do. I think I will make a small demo to test some of these things. I will share if I do. One unique thing I am doing is using TanStack Start and most registries are using Next.

[jkinley]

Do all registry items now get this?

  "$schema": "https://ui.shadcn.com/schema/registry-item.json",

If so, it is not shown in all the docs examples.

[BitWise-0x]

dunno. I think I answered your question I suppose make a feature request...