Registry

Configure the Blue Yonder @by-es registry in components.json and add components with the shadcn CLI using npx, pnpx, or pnpm dlx.

The @by-es registry is a shadcn registry–compatible endpoint for the Blue Yonder Experience System. It lets you use the shadcn CLI to add small files—mostly re-exports of @by/experience-system primitives and a few composite examples—into your repo’s component folders. That workflow is optional: most teams install @by/experience-system directly and import from the package; see Installation for the recommended setup.

Prerequisites

A valid components.json at the project root, matching the official JSON schema (required keys include style, tailwind with config, css, baseColor, and cssVariables, rsc, and aliases with at least components and utils).
@by/experience-system (and its peers) installed so generated imports resolve.
Access to the hosted registry over HTTPS. The registry validates requests with a JFrog access token; the CLI must send that token when it fetches registry JSON (see below).

Registry configuration

Add a registries entry for @by-es pointing at the production registry URL and an Authorization header that reads your token from an environment variable (for example REGISTRY_TOKEN).

Below is a complete example: it registers @by-es, sets iconLibrary to @by/icons, and uses @/ aliases. Adjust tailwind.css, style, and paths to match your app.

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "src/index.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "iconLibrary": "@by/icons",
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "registries": {
    "@by-es": {
      "url": "https://registry.blueyonder.design/r/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

Set REGISTRY_TOKEN in the environment to a JFrog access token (for example from your JFrog profile). A common approach is .env.local in the app so the variable is present when you run shadcn add.

Install items with the CLI

Use the namespaced form @by-es/<item> so the CLI resolves items through your components.json registry entry.

npx shadcn@latest add @by-es/button
npx shadcn@latest add @by-es/search

Replace button or search with the registry item name you need.

Import path aliases (Vite and TypeScript)

If components.json uses @/… aliases, the CLI writes those paths into new files. Vite must resolve @ to your source root, and TypeScript needs the same mapping.

In your Vite config, add a resolve.alias (adjust the target if your sources are not under ./src):

resolve: {
  alias: {
    '@': resolve(__dirname, '../../', './src'),
  },
},

In tsconfig.json, use moduleResolution bundler (typical for Vite) and paths for @/*:

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Without both, imports such as @/components/ui/... may fail at build time or in the editor.

Alternative: use relative aliases in components.json (for example "components": "src/components") and skip @/ configuration if you prefer.

What gets installed

UI primitives — Design-system components (for example accordion, alert, button, card, input). Each item adds a small file that re-exports from @by/experience-system.
Example components — search (search input with clear button) and ellipsis-with-tooltip (truncation with overflow-only tooltip).
by-es-setup — A base CSS file (fonts, Tailwind, theme, animation utilities). Wire styles and ThemeProvider using Installation as the primary guide.

Installation — Package install, Tailwind, and ThemeProvider
Migration — CCL/MUI → BY Experience System, preflight, by-es migrate scan
Components — Component usage in these guidelines