blocks/registry

330 notes in this subject, read out of this brain and free to use. This is page 5 of 6.

OpenCode MCP setup

For OpenCode: 1) Configure your registry in components.json with the registries object. 2) Run 'npx shadcn@latest mcp init --client opencode'. 3) Restart OpenCode. 4) Try prompts like 'Show me the components in the acme registry' or 'Create a landing page using items from the acme registry'.

MCP registry best practices for descriptions

Add concise, informative descriptions to registry items that help AI assistants understand what each item is for and how to use it.

MCP registry best practices for dependencies

List all 'dependencies' accurately in your registry items so MCP can install them automatically.

Security best practices for Open in v0 tokens

When using tokens for Open in v0 authentication, encrypt and expire tokens, and never expose production tokens in documentation or examples.

Open in v0 authentication implementation example

This Next.js API route example shows how to implement token-based authentication for Open in v0: ```typescript export async function GET(request: NextRequest) { const token = request.nextUrl.searchParams.get("token") if (!isValidToken(token)) { return NextResponse.json( { error: "Unauthorized", message: "Invalid or missing token", }, { status: 401 } ) } return NextResponse.json(registryItem) } ```

Open in v0 authentication implementation requirements

When implementing query parameter authentication for Open in v0: check for the token query parameter, validate it against your authentication system, return a 401 Unauthorized response if the token is invalid or missing. Both the shadcn CLI and Open in v0 will handle the 401 response and display an appropriate message to users.

Open in v0 query parameter authentication format

Open in v0 supports only query parameter authentication. Add a token query parameter to the registry URL like: https://registry.company.com/r/hello-world.json?token=your_secure_token_here

OpenInV0Button component example

This example shows how to create an Open in v0 button component using shadcn/ui Button: ```tsx import { Button } from "@/components/ui/button" export function OpenInV0Button({ url }: { url: string }) { return ( <Button aria-label="Open in v0" className="h-8 gap-1 rounded-[6px] bg-black px-3 text-xs text-white hover:bg-black hover:text-white dark:bg-white dark:text-black" asChild > <a href={`https://v0.dev/chat/api/open?url=${url}`} target="_blank" rel="noreferrer" > Open in{" "} <svg viewBox="0 0 40 20" fill="none" xmlns="http://www.w3.org/2000/svg" className="h-5 w-5 text-current" > <path d="M23.3919 0H32.9188C36.7819 0 39.9136 3.13165 39.9136 6.99475V16.0805H36.0006V6.99475C36.0006 6.90167 35.9969 6.80925 35.9898 6.71766L26.4628 16.079C26.4949 16.08 26.5272 16.0805 26.5595 16.0805H36.0006V19.7762H26.5595C22.6964 19.7762 19.4788 16.6139 19.4788 12.7508V3.68923H23.3919V12.7508C23.3919 12.9253 23.4054 13.0977 23.4316 13.2668L33.1682 3.6995C33.0861 3.6927 33.003 3.68923 32.9188 3.68923H23.3919V0Z" fill="currentColor" ></path> <path d="M13.7688 19.0956L0 3.68759H5.53933L13.6231 12.7337V3.68759H17.7535V17.5746C17.7535 19.6705 15.1654 20.6584 13.7688 19.0956Z" fill="currentColor" ></path> </svg> </a> </Button> ) } ``` Usage: `<OpenInV0Button url="https://example.com/r/hello-world.json" />`

Open in v0 unsupported features

Open in v0 does not support cssVars, css, envVars, namespaced registries, or advanced authentication methods.

Open in v0 API endpoint URL format

To open a registry item in v0, use the endpoint https://v0.dev/chat/api/open?url=[URL] where [URL] is the publicly accessible URL of the registry item.

Public registries list location

The full list of open source registries is available at https://ui.shadcn.com/r/registries.json

Registry index auto-discovery with shadcn add and shadcn search

When you run `shadcn add` or `shadcn search`, the CLI automatically checks the registry index for the registry you are looking for and adds it to your `components.json` file.

Registry directory for namespaces only

You do not need to submit a public GitHub registry to the registry directory to use it with `owner/repo/item` addresses. The registry directory is only for namespaces such as `@acme`.

Steps to add a registry to the registry directory

To add a registry: 1. Add your registry to `apps/v4/registry/directory.json` in the shadcn/ui repository. 2. Run `pnpm validate:registries` to validate the registry directory. 3. Create a pull request to https://github.com/shadcn-ui/ui. After submission, the registry will be validated and reviewed by the team.

Registry requirements for open source submission

Registry requirements are: 1. The registry must be open source and publicly accessible. 2. The registry must be a valid JSON file that conforms to the registry schema specification. 3. The registry must be a flat registry with no nested items—`/registry.json` and `/component-name.json` files are expected to be in the root of the registry. 4. The `files` array, if present, must NOT include a `content` property.

Example valid registry JSON structure

Example of a valid registry.json file: ```json { "$schema": "https://ui.shadcn.com/schema/registry.json", "name": "acme", "homepage": "https://acme.com", "items": [ { "name": "login-form", "type": "registry:component", "title": "Login Form", "description": "A login form component.", "files": [ { "path": "registry/new-york/auth/login-form.tsx", "type": "registry:component" } ] }, { "name": "example-login-form", "type": "registry:component", "title": "Example Login Form", "description": "An example showing how to use the login form component.", "files": [ { "path": "registry/new-york/examples/example-login-form.tsx", "type": "registry:component" } ] } ] } ```

Dependency transparency in registries

All dependencies are clearly listed in registry items. Users can inspect registry items before installation using the `view` command to see all dependencies and what will be installed.

Registry namespaces start with @ symbol

Registry namespaces are prefixed with `@` and provide a way to organize and reference resources from different sources. The pattern for referencing resources is `@namespace/resource-name`. Examples include `@shadcn/button`, `@v0/dashboard`, `@acme/auth-utils`.

Namespace naming convention rules

Registry names must start with `@` symbol and contain only alphanumeric characters, hyphens, and underscores. Valid examples are `@v0`, `@acme-ui`, `@my_company`.

Decentralized namespace system design

The namespace system is intentionally decentralized. There is a central open source registry index for open source namespaces, but users are free to create and use any namespace they want. This gives complete flexibility to organize resources however makes sense for your organization.

Basic registry configuration with URL template

The simplest way to configure a registry is with a URL template string. The `{name}` placeholder is automatically replaced with the resource name. For example, in `"@acme": "https://registry.acme.com/resources/{name}.json"`, installing `@acme/button` becomes `https://registry.acme.com/resources/button.json`.

Advanced registry configuration with object format

For registries requiring authentication or additional parameters, use the object format with `url`, `headers`, and `params` fields. Example: `"@private": { "url": "https://api.company.com/registry/{name}.json", "headers": { "Authorization": "Bearer ${REGISTRY_TOKEN}" }, "params": { "version": "latest" } }`.

URL placeholder system for registries

Registry URLs support two placeholders: `{name}` (required) which is replaced with the resource name, and `{style}` (optional) which is replaced with the current style configuration. For example, with style set to `new-york`, installing `@themes/card` from `https://registry.example.com/{style}/{name}.json` resolves to `https://registry.example.com/new-york/card.json`.

Environment variables in registry configuration

Environment variables in the format `${VAR_NAME}` are automatically expanded from your environment (process.env). This works in URLs, headers, and params. For example, `${REGISTRY_TOKEN}` will be replaced with the value of `process.env.REGISTRY_TOKEN`. Set environment variables in `.env.local` and never commit actual tokens to version control.

Bearer token authentication for registries

Use Bearer token (OAuth 2.0) authentication by configuring headers: `"headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }`.

API key authentication for registries

Use API key authentication by configuring headers: `"headers": { "X-API-Key": "${API_KEY}" }`.

Basic authentication for registries

Use Basic authentication by configuring headers: `"headers": { "Authorization": "Basic ${BASE64_CREDENTIALS}" }`.

Query parameter authentication for registries

Use query parameter authentication by configuring params: `"params": { "api_key": "${API_KEY}", "client_id": "${CLIENT_ID}", "signature": "${REQUEST_SIGNATURE}" }`.

Multiple authentication methods in registry configuration

Some registries require multiple authentication methods combining headers and params. Example: `"@enterprise": { "url": "https://api.enterprise.com/v2/registry/{name}", "headers": { "Authorization": "Bearer ${ACCESS_TOKEN}", "X-API-Key": "${API_KEY}", "X-Workspace-Id": "${WORKSPACE_ID}" }, "params": { "version": "latest" } }`.

Resource validation in registry system

All resources fetched from registries are validated against the registry item schema before installation. This ensures structure validation, type safety, and prevents arbitrary code execution. Resources are data files, not executable scripts.

Environment variable security in registries

Environment variables used for authentication are never logged, expanded at runtime only (not stored), and isolated per registry. Each registry maintains its own authentication context.

HTTPS enforcement for registry URLs

Always use HTTPS for all registry URLs to ensure encrypted transport, certificate validation, and credential protection. Avoid HTTP registry URLs as they are vulnerable to man-in-the-middle attacks.

Content security in registry resources

Resources from registries are treated as data, not code. JSON parsing only is performed, schema validation is required, file paths are restricted to configured locations, and no script execution occurs. The CLI doesn't execute any code from registry resources.

Registry trust model

The namespace system operates on a trust model where you trust what you install. Only add registries you trust to your configuration. Registries must be explicitly configured in `components.json`. The CLI never automatically adds registries.

Registry dependency resolution with dependencies field

Resources can have dependencies across different registries defined in the `registryDependencies` field. Example: `"registryDependencies": ["@shadcn/card", "@v0/chart", "@acme/data-table", "@lib/data-fetcher", "@ai/analytics-prompt"]`. The CLI automatically resolves and installs all dependencies from their respective registries.

How dependency resolution works

When running `npx shadcn@latest add @namespace/resource`, the CLI: 1) Clears registry context to start fresh, 2) Fetches the main resource from the specified registry, 3) Recursively resolves dependencies from their respective registries, 4) Applies topological sorting to ensure proper installation order, 5) Deduplicates files based on target paths (last one wins), 6) Deep merges configurations (tailwind, cssVars, css, envVars).

File deduplication in dependency resolution

When installing resources with dependencies, files are deduplicated based on target paths with last one winning. For example, if installing `@acme/auth @custom/login-form`, the `login-form.ts` from `@custom/login-form` will override the `login-form.ts` from `@acme/auth` because it's resolved last.

Override third-party resources via dependencies

You can leverage the dependency resolution process to override any third-party resource by adding them to your custom resource under `registryDependencies` and overriding with your own custom values. The last resource in the dependency chain wins.

Resolution order example with multiple dependencies

When a resource has multiple registry dependencies like `"registryDependencies": ["@shadcn/card", "@vendor/chart", "@custom/card"]`, resolution order is: 1) `@shadcn/card` installs to `components/ui/card.tsx`, 2) `@vendor/chart` installs to `components/ui/chart.tsx`, 3) `@custom/card` overwrites `components/ui/card.tsx` if it has the same target path.

Key features of registry dependency resolution

The resolution system includes: 1) Source Tracking - each resource knows which registry it came from to avoid naming conflicts, 2) Circular Dependency Prevention - automatically detects and prevents circular dependencies, 3) Smart Installation Order - dependencies are installed first, then the resources that use them.

Cross-registry dependencies authentication

When a component has dependencies from different registries, the resolver maintains separate authentication contexts for each registry, resolves each dependency from its respective source, deduplicates files based on target paths, and merges configurations from all sources.

Versioning with query parameters

Implement versioning for registry resources using query parameters. Example: `"@versioned": { "url": "https://registry.example.com/{name}", "params": { "version": "v2" } }` resolves `@versioned/button` to `https://registry.example.com/button?version=v2`.

Dynamic version selection with environment variables

Use environment variables to control versions across your project: `"@stable": { "url": "https://registry.company.com/{name}", "params": { "version": "${REGISTRY_VERSION}" } }`. This allows you to set `REGISTRY_VERSION=v1.2.3` in production and override per environment.

Semantic versioning in registries

Implement semantic versioning with range support: `"@npm-style": { "url": "https://registry.example.com/{name}", "params": { "semver": "^2.0.0", "prerelease": "${ALLOW_PRERELEASE}" } }`.

Version resolution best practices

1) Use environment variables for version control across environments, 2) Provide sensible defaults using `${VAR:-default}` syntax, 3) Document version schemes clearly for registry users, 4) Support version pinning for reproducible builds, 5) Implement version discovery endpoints (e.g., `/versions/{name}`), 6) Cache versioned resources appropriately with proper cache headers.

Difference between GitHub registry and namespaced registry

GitHub addresses and namespaces solve different problems. Use a GitHub address when the registry is a public GitHub repository and you want users to install without configuring `components.json` (e.g., `npx shadcn@latest add acme/ui/button`). Use a namespace when you want a stable alias, custom hosting, authentication, request headers, query parameters or private registry support (e.g., `npx shadcn@latest add @acme/button`).

Registry not configured error

If you reference a registry that isn't configured, you get an error: "Unknown registry \"@non-existent\". Make sure it is defined in components.json as follows: { \"registries\": { \"@non-existent\": \"[URL_TO_REGISTRY]\" } }".

Missing environment variables error

If required environment variables are not set, you get an error: "Registry \"@private\" requires the following environment variables: • REGISTRY_TOKEN. Set the required environment variables to your .env or .env.local file.".

Resource not found error

404 Not Found error: "The item at https://registry.company.com/button.json was not found. It may not exist at the registry." This usually means the resource name is misspelled, the resource doesn't exist in the registry, or the registry URL pattern is incorrect.

Authentication failure errors for registries

401 Unauthorized error: "You are not authorized to access the item at https://api.company.com/button.json. Check your authentication credentials and environment variables." 403 Forbidden error: "Access forbidden for https://api.company.com/button.json. Verify your API key has the necessary permissions.".

Creating a custom registry

To make a registry compatible with the namespace system: 1) Implement the registry item schema - return JSON conforming to the registry item schema, 2) Support the URL pattern - include `{name}` in your URL template, 3) Define resource types - use appropriate `type` fields (e.g., `registry:ui`, `registry:lib`, `registry:ai`, `registry:theme`), 4) Handle authentication if needed - accept authentication via headers or query parameters, 5) Document your namespace - provide clear instructions for users to configure your registry.

Namespace parser regex pattern

The namespace parser uses the regex pattern: `/^(@[a-zA-Z0-9](?:[a-zA-Z0-9-_]*[a-zA-Z0-9])?)\/(\$.+)$/` to ensure valid namespace formatting and proper component name extraction.

Registry resolution process steps

The complete resolution process: 1) Parse - extract namespace and component name from `@namespace/component`, 2) Lookup - find registry configuration for `@namespace`, 3) Build URL - replace placeholders with actual values, 4) Set Headers - apply authentication headers if configured, 5) Fetch - retrieve component from the resolved URL, 6) Validate - ensure response matches registry item schema, 7) Resolve Dependencies - recursively fetch any registry dependencies.

Best practices for registry configuration

1) Use environment variables for sensitive data like API keys and tokens, 2) Namespace your registry with a unique, descriptive name, 3) Document authentication requirements clearly for users, 4) Implement proper error responses with helpful messages, 5) Cache registry responses when possible to improve performance, 6) Support style variants if your components have multiple themes.

Troubleshooting resources not found

If resources are not found: 1) Verify the registry URL is correct and accessible, 2) Check that the `{name}` placeholder is included in the URL, 3) Ensure the resource exists in the registry, 4) Confirm the resource type matches what the registry provides.

Configure multiple registries in components.json

Namespaced registries are configured in the `components.json` file under the `registries` field. You can configure multiple resource sources in one project, organizing by type, team, visibility, or version.

Troubleshooting registry authentication issues

If experiencing authentication issues: 1) Confirm environment variables are set correctly, 2) Verify API keys/tokens are valid and not expired, 3) Check that headers are being sent in the correct format.

Troubleshooting registry dependency conflicts

If experiencing dependency conflicts: 1) Review resources with the same name from different registries, 2) Use fully qualified names (`@namespace/resource`) to avoid ambiguity, 3) Check for circular dependencies between registries, 4) Ensure resource types are compatible when mixing registries.

registry.json schema URL

The schema for registry.json is located at https://ui.shadcn.com/schema/registry.json.

registry.json include property format

The include property accepts an array of relative paths to explicit registry.json files. Folder shorthand is not supported. Each path must point directly to a registry.json file. Included registry.json files may omit the name and homepage fields, which are required only on the root registry.json.

Give your agent this brain