Fable UI's canonical public install origin is https://fable-ui.shobky.com/r/<item>.json. Install into a Next.js app with shadcn/ui, inspect the proposed changes, and avoid --overwrite unless you have reviewed the exact collision.
Initialize shadcn/ui#
If the Next.js app does not yet have components.json, initialize the supported Rhea preset first:
pnpm dlx shadcn@latest init --preset rhea --base radix --yesThis generates style: "radix-rhea" in components.json. radix-rhea is the generated style name, not a valid value for the CLI's --preset option. On Windows, use pnpm.cmd if PowerShell blocks the pnpm shim.
Quickstart#
Install the minimal example chat:
pnpm dlx shadcn@latest add https://fable-ui.shobky.com/r/quickstart.jsonIt creates /fable-chat and /api/fable-chat; it does not replace /chat or /api/chat.
What the quickstart includes#
The stock quickstart registers and renders exactly two tools:
show_metricshow_next_actions
It is intentionally not a complete integration. It does not register confirmation, form, chart, editor, email, code, DataBrowser, driver, or get_rendered_data behavior. Add those surfaces through the AI SDK integration guide after defining the host callbacks, data access, and authorization boundary.
Add server-only provider settings to .env.local:
FABLE_AI_PROVIDER=google
FABLE_AI_MODEL=gemini-3-flash-preview
FABLE_AI_API_KEY=replace-with-the-real-secretDo not write FABLE_AI_API_KEY=$OPENAI_API_KEY: .env.local does not expand shell variables. Put the actual intended value in FABLE_AI_API_KEY, keep it out of version control, and never print it.
Full catalog#
All 13 public items use the hosted URL form below. core is directly installable, but surface items normally bring it in transitively.
| Item | Category | Tool or role |
|---|---|---|
core | Foundation | Shared renderer, schemas, provider, and data-source registry. |
metric-card | Surface | show_metric |
suggested-actions | Surface | show_next_actions |
confirmation-card | Surface | request_confirmation |
form-card | Surface | collect_input |
charts | Block | show_chart |
text-editor-card | Surface | show_text_editor |
email-composer-card | Surface | show_email_composer |
code-block-card | Surface | show_code_block |
data-browser | Block | show_table, show_data_browser, get_rendered_data |
rest-driver | Driver | Host-owned REST adapter |
firebase-driver | Driver | Host-owned Firestore adapter |
quickstart | Example block | Minimal two-tool chat |
# Foundation
pnpm dlx shadcn@latest add https://fable-ui.shobky.com/r/core.json
# Surfaces and blocks
pnpm dlx shadcn@latest add https://fable-ui.shobky.com/r/metric-card.json
pnpm dlx shadcn@latest add https://fable-ui.shobky.com/r/suggested-actions.json
pnpm dlx shadcn@latest add https://fable-ui.shobky.com/r/confirmation-card.json
pnpm dlx shadcn@latest add https://fable-ui.shobky.com/r/form-card.json
pnpm dlx shadcn@latest add https://fable-ui.shobky.com/r/charts.json
pnpm dlx shadcn@latest add https://fable-ui.shobky.com/r/text-editor-card.json
pnpm dlx shadcn@latest add https://fable-ui.shobky.com/r/email-composer-card.json
pnpm dlx shadcn@latest add https://fable-ui.shobky.com/r/code-block-card.json
pnpm dlx shadcn@latest add https://fable-ui.shobky.com/r/data-browser.json
# Optional data drivers
pnpm dlx shadcn@latest add https://fable-ui.shobky.com/r/rest-driver.json
pnpm dlx shadcn@latest add https://fable-ui.shobky.com/r/firebase-driver.json
# Minimal example chat
pnpm dlx shadcn@latest add https://fable-ui.shobky.com/r/quickstart.jsonInstalled target categories#
The CLI maps @components, @lib, and @hooks targets through your host components.json. Confirm those aliases first. Every public item can install one or more of these categories:
| Category | Typical installed target |
|---|---|
| Foundation | lib/fable-ui/core/* |
| Surface and block source | components/fable-ui/<item>/* |
| Tool contract | lib/fable-ui/tools/* |
| Model manifest | lib/fable-ui/manifests/* |
| Shared hook | hooks/* |
| Driver adapter | lib/fable-ui/drivers/rest/* or lib/fable-ui/drivers/firebase/* |
| shadcn UI primitive | Host components/ui/* files resolved from item dependencies |
| Quickstart route | app/fable-chat/page.tsx, app/api/fable-chat/route.ts |
| Quickstart UI and config | components/fable-ui/chat/*, lib/fable-ui/quickstart/* |
| Quickstart notes | docs/fable-ui/quickstart.md |
app/... route targets are explicit. The short aliases are intentionally host-resolved so an installed item follows the destination configured by that app.
Before and after install#
Preview a hosted item before accepting changes:
pnpm dlx shadcn@latest add https://fable-ui.shobky.com/r/metric-card.json --dry-runAfter each item, run the host app's TypeScript check. This catches alias, existing primitive, and transitive dependency problems close to the installation that caused them.
pnpm exec tsc --noEmitOn Windows, if PowerShell blocks pnpm.ps1, use the executable shim instead:
pnpm.cmd dlx shadcn@latest add https://fable-ui.shobky.com/r/metric-card.json
pnpm.cmd exec tsc --noEmitFirebase and pnpm 11#
Installing firebase-driver can stop with ERR_PNPM_IGNORED_BUILDS for @firebase/util and protobufjs. Do not approve build scripts automatically. Review the scripts and deployment runtime, record an explicit allowBuilds decision, then retry. A compile-only mock can deny both scripts, but that is not proof that a production Firebase application should do the same. See Firebase for the complete policy example.
Troubleshooting shadcn dependencies#
If a chat primitive cannot be resolved, confirm that your components.json uses a shadcn style compatible with the installed dependencies. The quickstart uses current chat primitives such as message-scroller, message, bubble, and marker.
Use shadcn add --dry-run rather than copying raw registry view output. The CLI transforms item aliases and resolved primitive dependencies for your host app.