# API Reference · JGuang UI

> Programmatic API for working with registries, schemas and presets.

- Page: https://jiguang132.com/systems/jguang-ui/docs/registry/api-reference
- Based on: shadcn/ui documentation (MIT) @ bc0705384b51252af26dcc65425b216bf5eb063c

The `JGuang UI Registry` package exposes a set of programmatic APIs in addition to the CLI.
You can use these to fetch and resolve registry items, validate registry JSON,
and build custom tooling on top of the registry.

Each API is available under a dedicated subpath import.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```


  The CLI commands themselves are not part of the public API. Only the imports
  documented below are considered stable.


## JGuang UI/registry

Fetch and resolve items from configured registries.

Most functions accept an options object. The two options below are common to all
of them. In the examples that follow, `config` refers to this optional value —
omit it to use the built-in registries.

### config

- **Type:** `Partial<Config>`
- **Default:** built-in registries only

The resolved contents of your `components.json` file. Its `registries` field
maps a namespace (e.g. `@acme`) to a URL and any authentication headers or
environment variables required to reach it.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

### useCache

- **Type:** `boolean`
- **Default:** `true`

Registry responses are cached **in memory for the lifetime of the process**,
keyed by the resolved URL. Because the in-flight promise is cached, concurrent
requests for the same URL are de-duplicated into a single fetch.

Leave this enabled for one-off scripts and CLI runs. Set it to `false` in
long-running processes (servers, watchers, the MCP server) where the registry
can change between requests and you need fresh data each time.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

### getRegistry

Fetch a single registry by name.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

### getRegistryItems

Fetch one or more registry items by their qualified names.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

Returns an array of registry items:

```json showLineNumbers
[
  {
    "name": "button",
    "type": "registry:ui",
    "dependencies": ["@radix-ui/react-slot"],
    "files": [
      {
        "path": "ui/button.tsx",
        "type": "registry:ui",
        "content": "..."
      }
    ]
  }
]
```

### resolveRegistryItems

Resolve multiple items together with their registry dependencies, merged into a
single tree. Unlike [`getRegistryItems`](#getregistryitems), which returns the
items as a list, this walks each item's `registryDependencies` and flattens
everything — files, dependencies, CSS variables — into one installable object.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

Returns a single merged tree:

```json showLineNumbers
{
  "dependencies": ["@radix-ui/react-slot", "@radix-ui/react-dialog"],
  "files": [
    { "path": "ui/button.tsx", "type": "registry:ui", "content": "..." },
    { "path": "ui/card.tsx", "type": "registry:ui", "content": "..." },
    { "path": "ui/dialog.tsx", "type": "registry:ui", "content": "..." }
  ],
  "cssVars": {
    "theme": {
      "font-heading": "Poppins, sans-serif"
    },
    "light": {
      "brand": "oklch(0.205 0.015 18)"
    },
    "dark": {
      "brand": "oklch(0.205 0.015 18)"
    }
  },
  "docs": ""
}
```

### getRegistries

Fetch the registry directory.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

Returns an array of registry entries:

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

### searchRegistries

Search across one or more registries with fuzzy matching.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

Returns matching items wrapped in pagination metadata:

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

### loadRegistry

Read and resolve a local `registry.json` file from disk, following any
`include` references, and return the registry catalog.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

The returned catalog lists every item but **omits file contents** — like a
built `registry.json` index.


  [`getRegistry`](#getregistry) fetches a **remote** registry over the network
  (by namespace, URL or GitHub address) and expects the served catalog to
  already be flattened — it rejects catalogs that still use `include`.
  `loadRegistry` reads a **local** `registry.json` from disk and resolves
  `include` references itself.


### loadRegistryItem

Read a single item from a local `registry.json` by name, with its file contents
read from disk and inlined.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

Returns a fully resolved registry item with file contents:

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```


  [`getRegistryItems`](#getregistryitems) resolves items from a **remote**
  registry over the network. `loadRegistryItem` builds a single item on demand
  from your **local** source files, reading each file from disk. Use it in a
  dynamic route that serves `registry-item.json` responses.


### Errors

All registry functions throw typed errors that extend `RegistryError`. Use the
`RegistryErrorCode` enum or `instanceof` checks to handle them.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

Available error classes:

- `RegistryError`
- `RegistryNotFoundError`
- `RegistryUnauthorizedError`
- `RegistryForbiddenError`
- `RegistryFetchError`
- `RegistryNotConfiguredError`
- `RegistryLocalFileError`
- `RegistryParseError`
- `RegistryValidationError`
- `RegistryItemNotFoundError`
- `RegistriesIndexParseError`
- `RegistryMissingEnvironmentVariablesError`
- `RegistryInvalidNamespaceError`

## JGuang UI/schema

The Zod schemas used to validate `registry.json`, `registry-item.json` and
`components.json`. Useful for validating registry data in your own tooling.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

Key schemas:

- `registrySchema`
- `registryItemSchema`
- `registryItemFileSchema`
- `registryItemTypeSchema`
- `registryItemCssVarsSchema`
- `registryItemTailwindSchema`
- `registryBaseColorSchema`
- `configSchema`
- `presetSchema`

Inferred types are exported alongside them:

- `Registry`
- `RegistryItem`
- `RegistryBaseItem`
- `RegistryFontItem`
- `Preset`
- `ConfigJson`

## JGuang UI/preset

Encode, decode and validate theme presets, plus the preset option constants used
by the theme editor.

### encodePreset

Encode a `Partial<PresetConfig>` into a short, URL-safe preset code. Any fields
you omit fall back to `DEFAULT_PRESET_CONFIG`.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

Returns a version-prefixed string:

```ts showLineNumbers
"bJ4FLU0"
```

### decodePreset

Decode a preset code back into a full `PresetConfig`. Returns `null` if the code
is missing or invalid.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

Returns the resolved config (omitted fields are filled with their defaults):

```json
{
  "style": "vega",
  "baseColor": "stone",
  "theme": "blue",
  "chartColor": "neutral",
  "iconLibrary": "lucide",
  "font": "geist",
  "fontHeading": "inherit",
  "radius": "large",
  "menuAccent": "subtle",
  "menuColor": "default"
}
```

```ts
decodePreset("not-a-code") // null
```

### Other exports

Additional functions for validating codes and generating random presets:

- `isPresetCode`
- `isValidPreset`
- `generateRandomConfig`
- `generateRandomPreset`
- `toBase62`
- `fromBase62`

Constants:

- `PRESET_BASES`
- `PRESET_STYLES`
- `PRESET_BASE_COLORS`
- `PRESET_THEMES`
- `PRESET_ICON_LIBRARIES`
- `PRESET_FONTS`
- `PRESET_FONT_HEADINGS`
- `PRESET_RADII`
- `PRESET_MENU_ACCENTS`
- `PRESET_MENU_COLORS`
- `PRESET_CHART_COLORS`
- `DEFAULT_PRESET_CONFIG`

---

Index of all JGuang resources: https://jiguang132.com/llms.txt