Namespaces

Core Idea

Namespaced registries (@name) let one project configure and consume multiple resource sources (components, hooks, AI prompts, themes, config) at once — a decentralized system with no central naming authority, resolved via components.json#registries.

Key Concepts

• Namespace format: @namespace/resource-name; name must start with @, contain only alphanumerics/hyphens/underscores. Parser regex: /^(@[a-zA-Z0-9](?:[a-zA-Z0-9-_]*[a-zA-Z0-9])?)\/(.+)$/.
• Decentralized: No central authority — you can create any @namespace you want; a central open-source index exists only as an opt-in shortcut (see Registry Directory).
• URL template placeholders: {name} (required) is replaced with the resource name; {style} (optional) is replaced with the project's configured style (e.g. new-york), letting a registry serve per-style variants.
• Basic vs. advanced config: A registry entry can be a plain URL template string, or an object with url, headers, and params for auth/versioning.
• GitHub address vs. namespace: Use owner/repo/item (no config needed) for public GitHub repos; use @namespace when you need a stable alias, custom hosting, auth, headers, params, or private-registry support.
• Dependency resolution algorithm: add @namespace/resource clears registry context → fetches the main resource → recursively resolves registryDependencies from their respective registries → topologically sorts → deduplicates files by target path (last one wins) → deep-merges configs (tailwind, cssVars, css, envVars).
• Override pattern: To customize a third-party item, create your own item with registryDependencies: ["@vendor/original"] plus your own cssVars/files — installs the original then overlays your changes (last-resolved wins on same target path).
• Versioning via params: No built-in version field; registries implement versioning themselves via query params (params: { "version": "v2" } or ${REGISTRY_VERSION} env-driven).

Code Examples

{
  "registries": {
    "@acme-ui": "https://registry.acme.com/ui/{name}.json",
    "@acme-internal": {
      "url": "https://internal.acme.com/registry/{name}.json",
      "headers": { "Authorization": "Bearer ${INTERNAL_TOKEN}" }
    }
  }
}

• O que demonstra: mistura de config simples (string) e avançada (objeto com headers) no mesmo arquivo, organizando registries por propósito/time.

{
  "name": "custom-button",
  "type": "registry:ui",
  "registryDependencies": ["@vendor/button"],
  "cssVars": { "light": { "--button-bg": "purple" } }
}

• O que demonstra: padrão de override — instala o item de terceiro (@vendor/button) e sobrescreve só o cssVars, sem duplicar os arquivos.

npx shadcn@latest add @v0/dashboard
npx shadcn@latest add @acme/header @lib/auth-utils @ai/chatbot-rules
npx shadcn@latest view @acme/button
npx shadcn@latest search @acme --query "auth"

• O que demonstra: comandos CLI (add, view, search) operando com sintaxe de namespace, incluindo instalação múltipla cross-registry numa chamada só.

Reference Tables

Placeholder	Required	Resolves to
{name}	Yes	resource name from @namespace/resource-name
{style}	No	project's configured style (e.g. new-york)

CLI command	Purpose
add @ns/item	install (accepts URL, local file, or namespace)
view @ns/item	inspect payload before installing
search @ns --query X	search within a registry
list @ns	alias for search with no query
registry add @ns=URL_TEMPLATE	register a namespace in components.json

Anti-patterns

• Hardcoding tokens in components.json: always ${VAR} + .env.local; the CLI never logs expanded env var values.
• HTTP registry URLs: always use HTTPS to protect headers/tokens in transit.
• Relying on install order without checking resolution order: last-resolved registryDependencies entry wins on same target path — list overrides last, originals first.
• Assuming registries auto-discover: the CLI never adds a registry automatically; every @namespace must be explicitly configured.

Key Takeaways

1. Namespace config lives entirely in components.json#registries; no separate MCP or auth config format exists.
2. The override pattern (depend on the original + supply your own diffs) is the idiomatic way to customize any third-party registry item without forking it.
3. npx shadcn@latest view @ns/item is the safe way to inspect a registry item's full payload before installing — resources are validated JSON data, never executed as code.
4. Error messages are specific and actionable: unknown registry names the exact components.json snippet needed; missing env vars name the exact variable; 401/403 map to auth/permission issues respectively.
5. Registries composing dependencies across multiple sources maintain separate auth contexts per registry and detect circular dependencies automatically.

Connects To

• registry-authentication (ch102): full detail on the headers/params auth patterns referenced here.
• registry-item-json (ch108): registryDependencies field accepts namespace addresses per this spec.
• registry-index (ch105): the opt-in central directory for open-source namespaces.
• mcp (ch097): MCP prompts consume the same @namespace syntax.