Installation

Fable UI ships as a public shadcn registry. Install items into a Next.js + shadcn/ui app and own the copied source.

Quickstart#

Install the production quickstart chat. It creates /fable-chat and /api/fable-chat; it does not overwrite /chat or /api/chat.

pnpm dlx shadcn@latest add shobky/fable-ui/quickstart

If your app already has shadcn primitives such as button, input, card, badge, or skeleton, answer no when the CLI asks whether to overwrite them.

Troubleshooting: missing shadcn registry item#

You may see an error like this during installation:

CopyThe item at https://ui.shadcn.com/r/styles/new-york/message-scroller.json was not found.

This usually means your app's components.json is pointing the shadcn CLI to a style that does not include one of the newer chat primitives used by the Fable UI quickstart.

The quickstart depends on newer shadcn chat components such as message-scroller, so the CLI needs to resolve them from a compatible shadcn style.

Check your components.json:

Copy{
  "style": "radix-rhea"
}

Avoid styles that cannot resolve the chat components in your current setup:

Copy{
  "style": "new-york"
}

After updating components.json, run the quickstart install command again.

Fable UI does not control this error directly. The shadcn CLI reads your local components.json to decide which upstream style registry to use when resolving shadcn dependencies.

Troubleshooting: raw shadcn placeholders#

Some raw shadcn registry views can show implementation-only helpers such as IconPlaceholder or paths like @/app/(create)/components/icon-placeholder. Those should not appear in files installed by shadcn add; the add command transforms icons and paths for your app's components.json.

Use the install preview path when checking what will land in your app:

Copypnpm dlx shadcn@latest add shobky/fable-ui/data-browser --dry-run --view

If installed files still contain IconPlaceholder, IconPlaceHolder, @/app/(create), or @/registry/, upgrade to shadcn@latest and rerun the add command. Do not copy raw shadcn view output into your app.

Fable registry items do not declare shadcn primitive implementation packages such as radix-ui, @radix-ui/react-slot, or Base UI packages. The shadcn CLI resolves button, card, dialog, select, and other UI dependencies from the host app's components.json, then installs the packages required by those resolved components. If your host app keeps existing primitives, make sure those local files already have their own imports backed by installed dependencies.

Add the model configuration to .env.local:

CopyFABLE_AI_PROVIDER=google
FABLE_AI_MODEL=gemini-3-flash-preview
FABLE_AI_API_KEY=your-provider-api-key

Supported providers are google, anthropic, openai, openrouter, mistral, and deepseek. The quickstart uses one API key variable no matter which provider you choose. Restart your dev server, open /fable-chat, and start chatting.

When the variables are missing, the chat responds with a setup message that lists the exact variables to add.

Individual Components#

Install one surface at a time:

pnpm dlx shadcn@latest add shobky/fable-ui/metric-card

Other installable items:

pnpm dlx shadcn@latest add shobky/fable-ui/suggested-actions

pnpm dlx shadcn@latest add shobky/fable-ui/confirmation-card

pnpm dlx shadcn@latest add shobky/fable-ui/form-card

pnpm dlx shadcn@latest add shobky/fable-ui/data-browser

Optional Data Drivers#

DataBrowser works with static rows out of the box. Install a driver only when the host app wants registered resources backed by its own APIs or Firestore.

pnpm dlx shadcn@latest add shobky/fable-ui/rest-driver

pnpm dlx shadcn@latest add shobky/fable-ui/firebase-driver

What Gets Installed#

Fable items copy source into host-safe locations:

Copycomponents/fable-ui/<item>/*
lib/fable-ui/tools/*
lib/fable-ui/manifests/*

In registry.json, path is the source file in this repository and target is where the file lands in the host app. Component and library files use shadcn-aware aliases such as @components/..., @lib/..., and @hooks/... so the CLI can map them through the host app's components.json. Next routes and pages target explicit app/... paths.

Eval prompts live in this repository for product review and routing checks. They are not installed by default unless a future item explicitly marks them as runtime files.

Quickstart routes install to:

Copyapp/fable-chat/page.tsx
app/api/fable-chat/route.ts
components/fable-ui/chat/*
lib/fable-ui/quickstart/*

The quickstart includes metric-card and suggested-actions tool rendering. Driver routes, auth, API keys, databases, and permissions stay in the host app. Registry items install UI, tool contracts, manifests, and optional driver adapters.

Next Steps#

Add more Fable UI surfaces as the assistant needs them:

pnpm dlx shadcn@latest add shobky/fable-ui/confirmation-card

pnpm dlx shadcn@latest add shobky/fable-ui/form-card

Configure a data source when tool calls need to browse host-owned data:

pnpm dlx shadcn@latest add shobky/fable-ui/data-browser

pnpm dlx shadcn@latest add shobky/fable-ui/rest-driver

Inspect First#

Use shadcn to inspect or dry-run before accepting changes:

Copypnpm dlx shadcn@latest view shobky/fable-ui/metric-card
pnpm dlx shadcn@latest add shobky/fable-ui/metric-card --dry-run

Tags Later#

Current docs use unpinned GitHub install commands. Once releases exist, pin a tag:

Copypnpm dlx shadcn@latest add shobky/fable-ui/metric-card#v0.1.0