Skip to main content
Fragments Cloud

Documentation

Getting Started

Install governed source from the Cloud Registry with a project API key, or use the public npm package without a Cloud account.

Prefer registry source for governed Cloud projects — /registry. Use npm when source install is not the right delivery model.

Prerequisites

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

Path 1: Cloud Registry (API key required)

Writes verified source plus .fragments/registry-lock.json. Full commands: /registry.

The example uses the common @/* → src/* alias. Vanilla Vite does not create that alias: either configure it first or use --import-path "./fragments/ui" and relative imports from src/App.tsx.

Terminal
# 1. CLI
npm install -D @usefragments/cli

# 2. Cloud API key
export FRAGMENTS_API_KEY="fc_..."

# 3. Install source
npx @usefragments/cli registry add --all \
  --to src/fragments/ui \
  --import-path "@/fragments/ui"

# 4. Verify
npx @usefragments/cli registry status

5–7. Import styles, wrap providers, import components from @/fragments/ui:

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>
  );
}

Path 2: npm (no Cloud account required)

Use when source install is not the right model. Migrate later with npx @usefragments/cli registry migrate.

npm install @usefragments/ui

Heavy optional peer dependencies such as recharts, shiki, and react-day-picker are needed only when using the components that consume them.

Import styles once (includes tokens), then wrap providers from @usefragments/ui. Older Next.js/package combinations may also need transpilePackages if the package or stylesheet is not compiled correctly (below).

App.tsx
import '@usefragments/ui/styles';
import type { ReactNode } from 'react';
import {
  ThemeProvider,
  TooltipProvider,
  ToastProvider,
} from '@usefragments/ui';

function App({ children }: { children: ReactNode }) {
  return (
    <ThemeProvider defaultMode="system">
      <TooltipProvider>
        <ToastProvider>{children}</ToastProvider>
      </TooltipProvider>
    </ThemeProvider>
  );
}

Framework setup

Vite

Import styles in the entry file. With a configured @/* alias, registry source uses @/fragments/ui/styles/globals.scss. In vanilla Vite, install with --import-path "./fragments/ui" and import ./fragments/ui/styles/globals.scss from src/App.tsx. npm uses @usefragments/ui/styles.

Next.js

Current Next.js releases can consume the npm package directly. If your version reports an untranspiled-package error or omits the stylesheet, opt into 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.

Basic usage

Compound API via dot notation (Card.Header). Use the import path for the installation method you chose:

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 registry install, set seeds with SCSS @use ... with():

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

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

Toggle with ThemeToggle or useTheme. Preview: /create.

AI tooling (MCP)

Hosted endpoint: https://app.usefragments.com/api/mcp. Docs: /mcp.

.cursor/mcp.json
{
  "mcpServers": {
    "fragments": {
      "type": "http",
      "url": "https://app.usefragments.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${FRAGMENTS_API_KEY}"
      }
    }
  }
}

Next steps