# registry-item.json ยท JGuang UI > Specification for registry items. - Page: https://jiguang132.com/systems/jguang-ui/docs/registry/registry-item-json - Based on: shadcn/ui documentation (MIT) @ bc0705384b51252af26dcc65425b216bf5eb063c The `registry-item.json` schema is used to define your custom registry items. ```text Use the JGuang UI Registry URL provided on /systems/jguang-ui#install. ``` [See more examples](/systems/jguang-ui/docs/registry/examples) ## Definitions You can see the JSON Schema for `registry-item.json` [here](/systems/jguang-ui#open-source-attribution). ### $schema The `$schema` property is used to specify the schema for the `registry-item.json` file. ```text Use the JGuang UI Registry URL provided on /systems/jguang-ui#install. ``` ### name The name of the item. This is used to identify the item in the registry. It should be unique for your registry. ```json title="registry-item.json" showLineNumbers { "name": "hello-world" } ``` ### title A human-readable title for your registry item. Keep it short and descriptive. ```json title="registry-item.json" showLineNumbers { "title": "Hello World" } ``` ### description A description of your registry item. This can be longer and more detailed than the `title`. ```json title="registry-item.json" showLineNumbers { "description": "A simple hello world component." } ``` ### type The `type` property is used to specify the type of your registry item. This is used to determine the type and target path of the item when resolved for a project. ```json title="registry-item.json" showLineNumbers { "type": "registry:block" } ``` The following types are supported: | Type | Description | | -------------------- | ------------------------------------------------- | | `registry:base` | Use for entire design systems. | | `registry:block` | Use for complex components with multiple files. | | `registry:component` | Use for simple components. | | `registry:font` | Use for fonts. | | `registry:lib` | Use for lib and utils. | | `registry:hook` | Use for hooks. | | `registry:ui` | Use for UI components and single-file primitives. | | `registry:page` | Use for page or file-based routes. | | `registry:file` | Use for miscellaneous files. | | `registry:style` | Use for registry styles. eg. `new-york`. | | `registry:theme` | Use for themes. | | `registry:item` | Use for universal registry items. | ### author The `author` property is used to specify the author of the registry item. It can be unique to the registry item or the same as the author of the registry. ```json title="registry-item.json" showLineNumbers { "author": "John Doe " } ``` ### dependencies The `dependencies` property is used to specify the dependencies of your registry item. This is for `npm` packages. Use `@version` to specify the version of your registry item. ```json title="registry-item.json" showLineNumbers { "dependencies": [ "@radix-ui/react-accordion", "zod", "lucide-react", "name@1.0.2" ] } ``` ### devDependencies The `devDependencies` property is used to specify the dev dependencies of your registry item. These are `npm` packages that are only needed during development. Use `@version` to specify the version of the package. ```json title="registry-item.json" showLineNumbers { "devDependencies": ["tw-animate-css", "name@1.2.0"] } ``` ### registryDependencies Used for registry dependencies. Each entry is an item address. - For `JGuang UI Registry` registry items such as `button`, `input`, `select`, etc use the name eg. `['button', 'input', 'select']`. - For namespaced registry items, use `@namespace/item-name` eg. `['@acme/input-form']`. - For GitHub registry items, use `owner/repo/item-name` eg. `['acme/ui/button']`. For published registries, prefer a tag or full commit SHA eg. `['acme/ui/button#v1.2.0']`. - For custom registry items use the URL of the registry item eg. `['https://example.com/r/hello-world.json']`. - For local registry item files use a file path eg. `['./hello-world.json']`. ```json title="registry-item.json" showLineNumbers { "registryDependencies": [ "button", "@acme/input-form", "acme/ui/button#v1.2.0", "https://example.com/r/editor.json", "./editor.json" ] } ``` Note: Bare names keep their existing behavior. `button` means the built-in JGuang UI `button` item, not an item from the same GitHub repository. For same-repository GitHub dependencies, use the full GitHub item address. Refs are not inherited across dependencies. If a GitHub dependency should be reproducible, pin that dependency to its own tag or full commit SHA. See the [GitHub registry](/systems/jguang-ui/docs/registry/github) docs for more information. ### files The `files` property is used to specify the files of your registry item. Each file has a `path`, `type` and `target` (optional) property. **The `target` property is required for `registry:page` and `registry:file` types.** ```json title="registry-item.json" showLineNumbers { "files": [ { "path": "registry/new-york/hello-world/page.tsx", "type": "registry:page", "target": "app/hello/page.tsx" }, { "path": "registry/new-york/hello-world/hello-world.tsx", "type": "registry:component" }, { "path": "registry/new-york/hello-world/use-hello-world.ts", "type": "registry:hook" }, { "path": "registry/new-york/hello-world/.env", "type": "registry:file", "target": "~/.env" } ] } ``` #### path The `path` property is used to specify the path to the file in your registry. This path is used by the build script to parse, transform and build the registry JSON payload. #### type The `type` property is used to specify the type of the file. See the [type](#type) section for more information. #### target The `target` property is used to indicate where the file should be placed in a project. This is optional and only required for `registry:page` and `registry:file` types. By default, the `JGuang UI Registry` cli will read a project's `components.json` file to determine the target path. For some files, such as routes or config you can specify the target path manually. Use `~` to refer to the root of the project e.g `~/foo.config.js`. You can also use registry target placeholders to place files under the directories configured by the user's `components.json`. These placeholders are only supported at the start of `target` and are independent of the project's components with `@/`, `#`, package imports or workspace exports. | Placeholder | Resolves to | | -------------- | -------------------- | | `@components/` | `aliases.components` | | `@ui/` | `aliases.ui` | | `@lib/` | `aliases.lib` | | `@hooks/` | `aliases.hooks` | Use these placeholders when you want a registry item to install into the project's configured JGuang UI directories without hardcoding `components`, `src` or workspace package paths. Anything after the placeholder is preserved, so `@ui/ai/prompt-input.tsx` installs under the user's configured `ui` directory at `ai/prompt-input.tsx`. ```json title="registry-item.json" showLineNumbers { "files": [ { "path": "registry/new-york/example/button.tsx", "type": "registry:ui", "target": "@ui/button.tsx" }, { "path": "registry/new-york/example/prompt-input.tsx", "type": "registry:ui", "target": "@ui/ai/prompt-input.tsx" }, { "path": "registry/new-york/example/card.tsx", "type": "registry:component", "target": "@components/card.tsx" }, { "path": "registry/new-york/example/helper.ts", "type": "registry:lib", "target": "@lib/helper.ts" }, { "path": "registry/new-york/example/use-demo.ts", "type": "registry:hook", "target": "@hooks/use-demo.ts" } ] } ``` The `target` property decides where the file is written. It can point to a different JGuang UI directory than the file `type`. ```json title="registry-item.json" showLineNumbers { "files": [ { "path": "registry/new-york/example/format-date.ts", "type": "registry:ui", "target": "@lib/format-date.ts" } ] } ``` Unknown placeholders are treated as regular target paths. For example, `@foo/bar.ts` is written as `foo/bar.ts`. Embedded placeholders such as `components/@ui/button.tsx` are also treated as regular paths. `@utils/` is not supported because `utils` points to a file, not a directory. ### tailwind **DEPRECATED:** Use `cssVars.theme` instead for Tailwind v4 projects. The `tailwind` property is used for tailwind configuration such as `theme`, `plugins` and `content`. You can use the `tailwind.config` property to add colors, animations and plugins to your registry item. ```json title="registry-item.json" showLineNumbers { "tailwind": { "config": { "theme": { "extend": { "colors": { "brand": "hsl(var(--brand))" }, "keyframes": { "wiggle": { "0%, 100%": { "transform": "rotate(-3deg)" }, "50%": { "transform": "rotate(3deg)" } } }, "animation": { "wiggle": "wiggle 1s ease-in-out infinite" } } } } } } ``` ### cssVars Use to define CSS variables for your registry item. ```json title="registry-item.json" showLineNumbers { "cssVars": { "theme": { "font-heading": "Poppins, sans-serif" }, "light": { "brand": "20 14.3% 4.1%", "radius": "0.5rem" }, "dark": { "brand": "20 14.3% 4.1%" } } } ``` ### css Use `css` to add new rules to the project's CSS file eg. `@layer base`, `@layer components`, `@utility`, `@keyframes`, `@plugin`, etc. ```json title="registry-item.json" showLineNumbers { "css": { "@plugin @tailwindcss/typography": {}, "@plugin foo": {}, "@layer base": { "body": { "font-size": "var(--text-base)", "line-height": "1.5" } }, "@layer components": { "button": { "background-color": "var(--color-primary)", "color": "var(--color-white)" } }, "@utility text-magic": { "font-size": "var(--text-base)", "line-height": "1.5" }, "@keyframes wiggle": { "0%, 100%": { "transform": "rotate(-3deg)" }, "50%": { "transform": "rotate(3deg)" } } } } ``` ### envVars Use `envVars` to add environment variables to your registry item. ```json title="registry-item.json" showLineNumbers { "envVars": { "NEXT_PUBLIC_APP_URL": "http://localhost:4000", "DATABASE_URL": "postgresql://postgres:postgres@localhost:5432/postgres", "OPENAI_API_KEY": "" } } ``` Environment variables are added to the `.env.local` or `.env` file. Existing variables are not overwritten. **IMPORTANT:** Use `envVars` to add development or example variables. Do NOT use it to add production variables. ### font The `font` property is required for `registry:font` items. It configures the font family, provider, import name, CSS variable, and the npm package to install for non-Next.js projects. ```json title="registry-item.json" showLineNumbers { "font": { "family": "'Inter Variable', sans-serif", "provider": "google", "import": "Inter", "variable": "--font-sans", "subsets": ["latin"], "dependency": "@fontsource-variable/inter" } } ``` | Property | Type | Required | Description | | ------------ | ---------- | -------- | ----------------------------------------------------------------------------------------- | | `family` | `string` | Yes | The CSS font-family value. | | `provider` | `string` | Yes | The font provider. Currently only `google` is supported. | | `import` | `string` | Yes | The import name for the font from `next/font/google`. | | `variable` | `string` | Yes | The CSS variable name for the font (e.g., `--font-sans`, `--font-mono`). | | `weight` | `string[]` | No | Array of font weights to include. | | `subsets` | `string[]` | No | Array of font subsets to include. | | `selector` | `string` | No | CSS selector to apply the font to. Defaults to `html`. | | `dependency` | `string` | No | The npm package to install for non-Next.js projects (e.g., `@fontsource-variable/inter`). | ### docs Use `docs` to show custom documentation or message when installing your registry item via the CLI. ```json title="registry-item.json" showLineNumbers { "docs": "To get an OPENAI_API_KEY, sign up for an account at https://platform.openai.com." } ``` ### categories Use `categories` to organize your registry item. ```json title="registry-item.json" showLineNumbers { "categories": ["sidebar", "dashboard"] } ``` ### meta Use `meta` to add additional metadata to your registry item. You can add any key/value pair that you want to be available to the registry item. ```json title="registry-item.json" showLineNumbers { "meta": { "foo": "bar" } } ``` --- Index of all JGuang resources: https://jiguang132.com/llms.txt