API Reference

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.

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.

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.

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

getRegistry

Fetch a single registry by name.

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

getRegistryItems

Fetch one or more registry items by their qualified names.

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

Returns an array of registry items:

[
  {
    "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, which returns the items as a list, this walks each item's registryDependencies and flattens everything — files, dependencies, CSS variables — into one installable object.

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

Returns a single merged tree:

{
  "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.

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

Returns an array of registry entries:

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

searchRegistries

Search across one or more registries with fuzzy matching.

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

Returns matching items wrapped in pagination metadata:

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.

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 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.

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

Returns a fully resolved registry item with file contents:

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

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.

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.

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.

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

Returns a version-prefixed string:

"bJ4FLU0"

decodePreset

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

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

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

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

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