shadcn-ui/apps/v4/public/schema/registry-item.json

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the item. This is used to identify the item in the registry. It should be unique for your registry."
    },
    "type": {
      "type": "string",
      "enum": [
        "registry:lib",
        "registry:block",
        "registry:component",
        "registry:ui",
        "registry:hook",
        "registry:theme",
        "registry:page",
        "registry:file",
        "registry:style",
        "registry:base",
        "registry:font",
        "registry:item"
      ],
      "description": "The type of the item. This is used to determine the type and target path of the item when resolved for a project."
    },
    "description": {
      "type": "string",
      "description": "The description of the item. This is used to provide a brief overview of the item."
    },
    "title": {
      "type": "string",
      "description": "The human-readable title for your registry item. Keep it short and descriptive."
    },
    "author": {
      "type": "string",
      "description": "The author of the item. Recommended format: username <url>"
    },
    "dependencies": {
      "type": "array",
      "description": "An array of NPM dependencies required by the registry item.",
      "items": {
        "type": "string"
      }
    },
    "devDependencies": {
      "type": "array",
      "description": "An array of NPM dev dependencies required by the registry item.",
      "items": {
        "type": "string"
      }
    },
    "registryDependencies": {
      "type": "array",
      "description": "An array of registry items that this item depends on. Use the name of the item to reference shadcn/ui components and urls to reference other registries.",
      "items": {
        "type": "string"
      }
    },
    "files": {
      "type": "array",
      "description": "The main payload of the registry item. This is an array of files that are part of the registry item. Each file is an object with a path, content, type, and target.",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "The path to the file relative to the registry root."
          },
          "content": {
            "type": "string",
            "description": "The content of the file."
          },
          "type": {
            "type": "string",
            "enum": [
              "registry:lib",
              "registry:block",
              "registry:component",
              "registry:ui",
              "registry:hook",
              "registry:theme",
              "registry:page",
              "registry:file",
              "registry:style",
              "registry:base",
              "registry:item"
            ],
            "description": "The type of the file. This is used to determine the type of the file when resolved for a project."
          },
          "target": {
            "type": "string",
            "description": "The target path of the file. This is the path to the file in the project."
          }
        },
        "if": {
          "properties": {
            "type": {
              "enum": ["registry:file", "registry:page"]
            }
          }
        },
        "then": {
          "required": ["path", "type", "target"]
        },
        "else": {
          "required": ["path", "type"]
        }
      }
    },
    "tailwind": {
      "type": "object",
      "description": "The tailwind configuration for the registry item. This is an object with a config property. Use cssVars for Tailwind v4 projects.",
      "properties": {
        "config": {
          "type": "object",
          "properties": {
            "content": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "theme": {
              "type": "object",
              "additionalProperties": true
            },
            "plugins": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "cssVars": {
      "type": "object",
      "description": "The css variables for the registry item. This will be merged with the project's css variables.",
      "properties": {
        "theme": {
          "type": "object",
          "description": "CSS variables for the @theme directive. For Tailwind v4 projects only. Use tailwind for older projects.",
          "additionalProperties": {
            "type": "string"
          }
        },
        "light": {
          "type": "object",
          "description": "CSS variables for the light theme.",
          "additionalProperties": {
            "type": "string"
          }
        },
        "dark": {
          "type": "object",
          "description": "CSS variables for the dark theme.",
          "additionalProperties": {
            "type": "string"
          }
        }
      }
    },
    "css": {
      "type": "object",
      "description": "CSS definitions to be added to the project's CSS file. Supports at-rules, selectors, nested rules, utilities, layers, and more.",
      "additionalProperties": {
        "$ref": "#/definitions/cssValue"
      }
    },
    "envVars": {
      "type": "object",
      "description": "Environment variables required by the registry item. Key-value pairs that will be added to the project's .env file.",
      "additionalProperties": {
        "type": "string"
      }
    },
    "meta": {
      "type": "object",
      "description": "Additional metadata for the registry item. This is an object with any key value pairs.",
      "additionalProperties": true
    },
    "docs": {
      "type": "string",
      "description": "The documentation for the registry item. This is a markdown string."
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "The categories of the registry item. This is an array of strings."
      }
    },
    "extends": {
      "type": "string",
      "description": "The name of the registry item to extend. This is used to extend the base shadcn/ui style. Set to none to start fresh. This is available for registry:style items only."
    },
    "style": {
      "type": "string",
      "description": "The style configuration for the base. This is available for registry:base items only."
    },
    "iconLibrary": {
      "type": "string",
      "description": "The icon library to use for the base. This is available for registry:base items only."
    },
    "baseColor": {
      "type": "string",
      "description": "The base color configuration. This is available for registry:base items only."
    },
    "theme": {
      "type": "string",
      "description": "The theme configuration. This is available for registry:base items only."
    },
    "font": {
      "type": "object",
      "description": "Font metadata for registry:font items. Required for registry:font type.",
      "properties": {
        "family": {
          "type": "string",
          "description": "The font family name (e.g., 'Inter', 'JetBrains Mono')."
        },
        "provider": {
          "type": "string",
          "enum": ["google"],
          "description": "The font provider. Currently only 'google' is supported."
        },
        "import": {
          "type": "string",
          "description": "The import name for the font from next/font/google (e.g., 'Inter', 'JetBrains_Mono')."
        },
        "variable": {
          "type": "string",
          "description": "The CSS variable name for the font (e.g., '--font-sans', '--font-mono')."
        },
        "weight": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Array of font weights to include (e.g., ['400', '500', '600', '700'])."
        },
        "subsets": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Array of font subsets to include (e.g., ['latin', 'latin-ext'])."
        },
        "selector": {
          "type": "string",
          "description": "CSS selector to apply the font utility class to (e.g., 'h1, h2, h3'). Defaults to 'html'."
        },
        "dependency": {
          "type": "string",
          "description": "The npm package to install for the font in non-Next.js projects (e.g., '@fontsource-variable/inter', '@fontsource/lato')."
        }
      },
      "required": ["family", "provider", "import", "variable"]
    }
  },
  "required": ["name", "type"],
  "allOf": [
    {
      "if": {
        "properties": {
          "type": {
            "const": "registry:font"
          }
        }
      },
      "then": {
        "required": ["name", "type", "font"]
      },
      "else": {
        "properties": {
          "font": false
        }
      }
    },
    {
      "if": {
        "not": {
          "properties": {
            "type": {
              "const": "registry:base"
            }
          }
        }
      },
      "then": {
        "properties": {
          "style": false,
          "iconLibrary": false,
          "baseColor": false,
          "theme": false
        }
      }
    }
  ],
  "definitions": {
    "cssValue": {
      "oneOf": [
        {
          "type": "string",
          "description": "CSS property value or direct CSS string"
        },
        {
          "type": "object",
          "description": "Nested CSS properties, selectors, or at-rules. Empty objects are allowed for at-rules with no body.",
          "additionalProperties": {
            "$ref": "#/definitions/cssValue"
          }
        }
      ]
    }
  }
}