Skip to main content

Install

Component source copied into your app, or the npm package.

React 18+, Node.js 18+, TypeScript 5+ recommended.

Choose your path

Pick one and follow only its commands. Both ship the same components.

Source

Copies the components you name into your app. No account, no key. Each run writes the components plus what they import to src/fragments/ui, the globals stylesheet, and .fragments/registry-lock.json, then prints the packages to add.

Terminal
npx @usefragments/cli add button card checkbox alert

# then the line it prints, for example
pnpm add @base-ui/react

Imports use the @/* → src/* alias. Without one, pass --to and --import-path "./fragments/ui" on the first run. Later runs keep the lockfile's target.

App.tsx
import "@/fragments/ui/styles/globals.scss";
import type { ReactNode } from "react";
import { ThemeProvider, TooltipProvider, ToastProvider } from "@/fragments/ui";

function App({ children }: { children: ReactNode }) {
  return (
    <ThemeProvider defaultMode="system">
      <TooltipProvider>
        <ToastProvider>{children}</ToastProvider>
      </TooltipProvider>
    </ThemeProvider>
  );
}
Your own registry: publish your components from Fragments Cloud, then npx @usefragments/cli add button --registry acme/design-system. Connect a workspace to get a key. Every other command: Registry commands.

  1. Set up your framework

    Vite

    Import the stylesheet from your application entry file.

    With a configured @/* alias, source installs use @/fragments/ui/styles/globals.scss.

    Without an alias, install with --import-path "./fragments/ui" and import ./fragments/ui/styles/globals.scss from src/App.tsx.

    Package installs use @usefragments/ui/styles.

    Next.js

    Current Next.js releases consume the package directly.

    If your version reports an untranspiled-package error or omits the stylesheet, enable package transpilation:

    next.config.ts
    const nextConfig = {
  transpilePackages: ['@usefragments/ui'],
};

export default nextConfig;

    Import styles in app/layout.tsx.

    Set suppressHydrationWarning on <html>.

    Client-only UI needs 'use client' in the rendering file.

    Migrating from npm? Run npx @usefragments/cli registry migrate. Details: registry migrate.

  2. Render your first component

    Compound components use dot notation, such as Card.Header. Use the import path for your installation method.

    import { Button, Card, Input, Stack } from "@/fragments/ui";

function MyComponent() {
  return (
    <Card>
      <Card.Header>
        <Card.Title>Welcome</Card.Title>
      </Card.Header>
      <Card.Body>
        <Stack gap="sm">
          <Input placeholder="Enter your name" />
          <Button>Submit</Button>
        </Stack>
      </Card.Body>
    </Card>
  );
}

Theming

For a source install, set seeds with SCSS @use ... with():

styles/globals.scss
@use "@/fragments/ui/styles/globals.scss" with (
  $fui-brand: #6366f1,
  $fui-radius-style: "rounded"
);

This SCSS import path requires sass as a dev dependency in the consumer build.

Toggle with ThemeToggle or useTheme.

AI tooling (MCP)

Connect to the hosted endpoint at https://app.usefragments.com/api/mcp with OAuth. See the MCP guide for supported tools.

.cursor/mcp.json
{
  "mcpServers": {
    "fragments": {
      "url": "https://app.usefragments.com/api/mcp"
    }
  }
}

Registry commands

add copies source from the public usefragments-ui registry by default. --registry org/name selects a registry you published from Fragments Cloud (workspace key); --from or FRAGMENTS_UI_REGISTRY_ARTIFACT_URL points at a local or self-hosted artifact. npx @usefragments/cli check proves installed source against the lockfile. See the CLI reference for all flags.

add

Name components (any case), or take everything with --all. The first run picks the target from the registry's install profile; later runs keep the lockfile's:

Terminal
npx @usefragments/cli add button card
npx @usefragments/cli add --all
npx @usefragments/cli add button --registry acme/design-system
npx @usefragments/cli add button --to src/fragments/ui --import-path "@/fragments/ui"

status

Inspect the lockfile and installed source state:

Terminal
npx @usefragments/cli registry status

diff

Compare installed source against a registry artifact:

Terminal
npx @usefragments/cli registry diff

sync

Refresh installed source using the existing lockfile selection:

Terminal
npx @usefragments/cli registry sync

migrate

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

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

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

Lockfile and drift

npx @usefragments/cli 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 drift with npx @usefragments/cli registry status and npx @usefragments/cli registry diff, then refresh with npx @usefragments/cli registry sync.

Do not hand-edit managed files under src/fragments/ui. Change selection or refresh through the registry commands above.

Next steps