Registry

Install

Install the CLI, then set a Cloud API key:

npm install -D @usefragments/cli
export FRAGMENTS_API_KEY="fc_..."

Pull every component and package entrypoint into the default target:

npx @usefragments/cli registry add --all \
--to src/fragments/ui \
--import-path "@/fragments/ui"

That import path requires an @/* → src/* alias. For vanilla Vite, use --import-path "./fragments/ui" and relative imports from src/App.tsx.

The CLI discovers the hosted artifact from Fragments Cloud catalog metadata. Override only for local artifacts with --from or FRAGMENTS_UI_REGISTRY_ARTIFACT_URL.

Import styles once from the registry path:

import "@/fragments/ui/styles/globals.scss";
import { ThemeProvider, TooltipProvider, ToastProvider } from "@/fragments/ui";

Commands

add

Install selected components, or everything with --all:

npx @usefragments/cli registry add --all --to src/fragments/ui --import-path "@/fragments/ui"
npx @usefragments/cli registry add Button Card --to src/fragments/ui

status

Inspect the lockfile and installed source state:

npx @usefragments/cli registry status

diff

Compare installed source against a registry artifact:

npx @usefragments/cli registry diff

sync

Refresh installed source using the existing lockfile selection:

npx @usefragments/cli registry sync

migrate

Convert an existing @usefragments/ui app to registry source. Preview first:

npx @usefragments/cli registry migrate --dry-run
npx @usefragments/cli registry migrate

Migrate installs registry source, rewrites npm imports to @/fragments/ui, updates simple Next.js transpilePackages, and removes the npm UI package unless you pass --keep-package. See /cli.

Lockfile and drift

npx @usefragments/cli registry add writes source plus .fragments/registry-lock.json.

The lockfile pins the artifact version and file hashes so npx @usefragments/cli check can prove committed source still matches the registry.

Drift means local files no longer match the lockfile. Inspect with npx @usefragments/cli registry status and npx @usefragments/cli registry diff, then refresh with npx @usefragments/cli registry sync.

Next steps

• Getting Started — providers, framework notes, theming
• CLI Reference — full registry flags and options
• Components — browse the component catalog