Set up the private registry
Configure this once, then install connected SDK components or standalone UI into your app. The CLI copies editable source and its dependencies into your project.
Using SDK hooks only? Install the npm package and connect your provider. No registry setup is needed.
01Prepare your React app
Start with a React and TypeScript app using a framework supported by shadcn/ui, such as Next.js or Vite. Follow the shadcn/ui installation guide for your framework to configure Tailwind CSS, global styles and import aliases.
In your app's root directory, initialise shadcn/ui if you do not already have a components.json:
bunx --bun shadcn@4.23.0 initUsing npm or pnpm?
npx shadcn@4.23.0 initpnpm dlx shadcn@4.23.0 initKeep your existing configuration if shadcn/ui is already set up. The examples use the @/ import alias; use the paths configured in your app. In frameworks with server components, render interactive Dolfin components inside a client component with "use client".
02Get registry access
Request a registry token from your Dolfin contact if one has not been supplied. This install token is separate from your Dolfin API key and user authentication tokens. It authorises the CLI to download component source; it does not connect your app to the Dolfin API.
Make DOLFIN_REGISTRY_TOKEN available to the terminal running the CLI. For example, in a local macOS or Linux shell:
export DOLFIN_REGISTRY_TOKEN="your_registry_token"Replace the placeholder with your supplied token. Keep it in your local environment or CI secret store. This is a server-only/install-time secret: never commit the value, put it in browser code, or prefix it with NEXT_PUBLIC_ or VITE_. A framework's .env.local is not automatically an exported shell variable.
03Configure the Dolfin namespace
Merge this registries entry into your existing components.json. Preserve its other fields and any other registries. Keep the variable reference below literal; the CLI resolves it from your environment.
{
"registries": {
"@dolfin": {
"url": "https://registry.dolfinai.co/r/{name}.json",
"headers": { "Authorization": "Bearer ${DOLFIN_REGISTRY_TOKEN}" }
}
}
}The same @dolfin namespace serves both layers. Connected items use names such as ap-bills-table; their standalone counterparts use ui-ap-bills-table.
04Choose your first component
Setup is complete. Pick an example to install and render:
- SDK example: a connected Bills table. Add the component, then configure server authentication and
DolfinProvider. - UI example: a standalone Stat card. Pass display values directly, with no provider or API credentials.
Or browse the component catalog, select Connected SDK or Standalone UI, and copy that tab's install command. Each command installs the selected component and its dependencies; no starter component is required for every app.
If installation fails
For an authentication error, check that the token is exported in the same terminal, that the namespace matches the configuration above, and that your Dolfin contact has enabled access. API credentials cannot replace a registry token. For missing styles or import aliases, revisit your framework's shadcn/ui setup.