# Installation

How to install Frakment in your project.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

<DocsBaseSwitcher base="web" customBases={[{"href":"/docs/getting-started/installation","name":"web","title":"Web"},{"href":"/docs/getting-started/installation/native","name":"native","title":"Native"}]} />

Frakment is a set of components you install into your own project. There are two paths: use the CLI to fetch components from the registry, or copy the source files manually.

**What you'll get from this guide:**

- A working `components.json` with registry URL and import aliases
- Theme CSS variables injected into your globals
- `lib/utils.ts`, `lib/motion.ts`, and `lib/animation.ts`
- Six dependencies installed: `clsx`, `tailwind-merge`, `class-variance-authority`, `radix-ui`, `lucide-react`, `motion`
- Your first component installed and rendering

## Prerequisites [#prerequisites]

- **Node.js** 18 or newer
- **React** 19
- **Tailwind CSS** v4
- **TypeScript** (recommended)

Components target React 19 and Tailwind v4. For React 18, some components need `forwardRef` adjustments. For Tailwind v3, port the tokens from [Theming](/docs/guides/theming) manually.

## Use the CLI [#use-the-cli]

For all commands, flags, and registry format, see the [CLI Reference](/docs/libraries/cli).

<Steps>
<Step>
Run init
</Step>

```bash
npx frakment@latest init
```

Creates `components.json`, injects the theme block (tokens + dark mode + 9 utilities) into `globals.css` between `/* ==== FRAKMENT THEME START/END ==== */` markers, adds `lib/utils.ts`, and installs 6 dependencies: `class-variance-authority`, `clsx`, `tailwind-merge`, `radix-ui`, `lucide-react`, `motion`.

<Step>
Add components
</Step>

```bash
npx frakment@latest add bubble
```

Fetches `bubble.json`, resolves registry dependencies, resolves npm dependencies, writes source into `components/ui/`.

<Step>
Import and use
</Step>

```tsx title="bubble.tsx"
import { Bubble, BubbleContent } from "@/components/ui/message";

export default function Page() {
  return (
    <Bubble>
      <BubbleContent>Hello, Frakment.</BubbleContent>
    </Bubble>
  );
}
```
</Steps>

The `avatar` component ships with five AVIF avatars, embedded as base64 in `avatar.json` and written to `public/avatars/` on install.

## What you get [#what-you-get]

After `frakment init`, your project will have:

<FileTree>
<FileTreeFolder name="apps" defaultOpen>
<FileTreeFile name="components.json" />

<FileTreeFolder name="app" defaultOpen>
<FileTreeFile name="globals.css" />
</FileTreeFolder>

<FileTreeFolder name="lib" defaultOpen>
<FileTreeFile name="utils.ts" />

<FileTreeFile name="animation.ts" />

<FileTreeFile name="motion.ts" />
</FileTreeFolder>
</FileTreeFolder>
</FileTree>

- **`components.json`** - registry URL, import aliases, Tailwind CSS path. Read by the CLI on every `add`.
- **`app/globals.css`** - theme tokens (colors, radii, spacing) injected between `/* ==== FRAKMENT THEME START/END ==== */` markers, plus `.dark` variant and 9 utility classes.
- **`lib/utils.ts`** - `cn()` helper for merging Tailwind classes.
- **`lib/motion.ts`** - The per-component motion API. `parseMotion()` parses the `motion?: string` prop into duration and easing. `getTransition()` turns that into a CSS transition. `useReducedMotion()` and `useMotionGuard()` handle reduced motion and style overrides.
- **`lib/animation.ts`** - Motion tokens (`easeInOut`, `easeInOutQuad`, `easeOutExpo`, `easeSmoothOut`, `springSoft`, `durationFast`, `durationNormal`, `durationSlow`, `delayTight`) and the `parseAnimation()` parser. Still used by components that have not yet migrated to `lib/motion.ts`.

### Dependencies [#dependencies]

`frakment init` checks your `package.json` and installs any missing package:

- `clsx`
- `tailwind-merge`
- `class-variance-authority`
- `radix-ui`
- `lucide-react`
- `motion`

These are the current runtime dependencies. `radix-ui` and `motion` are being removed incrementally as components move to Frakment-owned primitives and `lib/motion.ts`.

The theme block includes `.dark` and `@custom-variant dark`. As soon as your app toggles `.dark` on `<html>` (via `next-themes`, a custom button, or anything else), components switch automatically - no extra config needed. See [Theming](/docs/guides/theming) for the full wiring.

## Existing Project [#existing-project]

Each framework guide includes an Existing Project section with the manual setup steps for that framework.

Pick your framework and follow that path.

<div id="choose-your-framework" className="scroll-mt-24" />

## Choose Your Framework [#choose-your-framework]

<div className="mt-8 grid gap-4 sm:grid-cols-2 sm:gap-6">

<LinkedCard href="/docs/getting-started/installation/next">
<svg
  role="img"
  viewBox="0 0 24 24"
  xmlns="http://www.w3.org/2000/svg"
  className="h-10 w-10"
  fill="currentColor"
>
  <title>Next.js</title>
  <path d="M11.5725 0c-.1763 0-.3098.0013-.3584.0067-.0516.0053-.2159.021-.3636.0328-3.4088.3073-6.6017 2.1463-8.624 4.9728C1.1004 6.584.3802 8.3666.1082 10.255c-.0962.659-.108.8537-.108 1.7474s.012 1.0884.108 1.7476c.652 4.506 3.8591 8.2919 8.2087 9.6945.7789.2511 1.6.4223 2.5337.5255.3636.04 1.9354.04 2.299 0 1.6117-.1783 2.9772-.577 4.3237-1.2643.2065-.1056.2464-.1337.2183-.1573-.0188-.0139-.8987-1.1938-1.9543-2.62l-1.919-2.592-2.4047-3.5583c-1.3231-1.9564-2.4117-3.556-2.4211-3.556-.0094-.0026-.0187 1.5787-.0235 3.509-.0067 3.3802-.0093 3.5162-.0516 3.596-.061.115-.108.1618-.2064.2134-.075.0374-.1408.0445-.495.0445h-.406l-.1078-.068a.4383.4383 0 01-.1572-.1712l-.0493-.1056.0053-4.703.0067-4.7054.0726-.0915c.0376-.0493.1174-.1125.1736-.143.0962-.047.1338-.0517.5396-.0517.4787 0 .5584.0187.6827.1547.0353.0377 1.3373 1.9987 2.895 4.3608a10760.433 10760.433 0 004.7344 7.1706l1.9002 2.8782.096-.0633c.8518-.5536 1.7525-1.3418 2.4657-2.1627 1.5179-1.7429 2.4963-3.868 2.8247-6.134.0961-.6591.1078-.854.1078-1.7475 0-.8937-.012-1.0884-.1078-1.7476-.6522-4.506-3.8592-8.2919-8.2087-9.6945-.7672-.2487-1.5836-.42-2.4985-.5232-.169-.0176-1.0835-.0366-1.6123-.037zm4.0685 7.217c.3473 0 .4082.0053.4857.047.1127.0562.204.1642.237.2767.0186.061.0234 1.3653.0186 4.3044l-.0067 4.2175-.7436-1.14-.7461-1.14v-3.066c0-1.982.0093-3.0963.0234-3.1502.0375-.1313.1196-.2346.2323-.2955.0961-.0494.1313-.054.4997-.054z" />
</svg>
<p className="mt-2 font-medium">Next.js</p>
</LinkedCard>

<LinkedCard href="/docs/getting-started/installation/astro">
<svg
  role="img"
  viewBox="0 0 24 24"
  xmlns="http://www.w3.org/2000/svg"
  className="h-10 w-10"
  fill="currentColor"
>
  <title>Astro</title>
  <path d="M16.074 16.86C15.354 17.476 13.917 17.895 12.262 17.895C10.23 17.895 8.527 17.263 8.075 16.412C7.914 16.9 7.877 17.458 7.877 17.814C7.877 17.814 7.771 19.564 8.988 20.782C8.988 20.15 9.501 19.637 10.133 19.637C11.216 19.637 11.215 20.582 11.214 21.349V21.418C11.214 22.582 11.925 23.579 12.937 24C12.7812 23.6794 12.7005 23.3275 12.701 22.971C12.701 21.861 13.353 21.448 14.111 20.968C14.713 20.585 15.383 20.161 15.844 19.308C16.0926 18.8493 16.2225 18.3357 16.222 17.814C16.2221 17.4903 16.1722 17.1685 16.074 16.86ZM15.551 0.6C15.747 0.844 15.847 1.172 16.047 1.829L20.415 16.176C18.7743 15.3246 17.0134 14.7284 15.193 14.408L12.35 4.8C12.3273 4.72337 12.2803 4.65616 12.2162 4.60844C12.152 4.56072 12.0742 4.53505 11.9943 4.53528C11.9143 4.5355 11.8366 4.56161 11.7727 4.60969C11.7089 4.65777 11.6623 4.72524 11.64 4.802L8.83 14.405C7.00149 14.724 5.23264 15.3213 3.585 16.176L7.974 1.827C8.174 1.171 8.274 0.843 8.471 0.6C8.64406 0.385433 8.86922 0.218799 9.125 0.116C9.415 0 9.757 0 10.443 0H13.578C14.264 0 14.608 0 14.898 0.117C15.1529 0.219851 15.3783 0.386105 15.551 0.6Z" />
</svg>
<p className="mt-2 font-medium">Astro</p>
</LinkedCard>

<LinkedCard href="/docs/getting-started/installation/gatsby">
<BrandIcon />

<p className="mt-2 font-medium">Gatsby</p>
</LinkedCard>

<LinkedCard href="/docs/getting-started/installation/laravel">
<BrandIcon />

<p className="mt-2 font-medium">Laravel</p>
</LinkedCard>

<LinkedCard href="/docs/getting-started/installation/react-router">
<BrandIcon />

<p className="mt-2 font-medium">React Router</p>
</LinkedCard>

<LinkedCard href="/docs/getting-started/installation/remix">
<BrandIcon />

<p className="mt-2 font-medium">Remix</p>
</LinkedCard>

<LinkedCard href="/docs/getting-started/installation/tanstack-router">
<BrandIcon />

<p className="mt-2 font-medium">TanStack Router</p>
</LinkedCard>

<LinkedCard href="/docs/getting-started/installation/vite">
<svg
  role="img"
  viewBox="0 0 24 24"
  xmlns="http://www.w3.org/2000/svg"
  className="h-10 w-10"
  fill="currentColor"
>
  <title>Vite</title>
  <path d="m8.286 10.578.512-8.657a.306.306 0 0 1 .247-.282L17.377.006a.306.306 0 0 1 .353.385l-1.558 5.403a.306.306 0 0 0 .352.385l2.388-.46a.306.306 0 0 1 .332.438l-6.79 13.55-.123.19a.294.294 0 0 1-.252.14c-.177 0-.35-.152-.305-.369l1.095-5.301a.306.306 0 0 0-.388-.355l-1.433.435a.306.306 0 0 1-.389-.354l.69-3.375a.306.306 0 0 0-.37-.36l-2.32.536a.306.306 0 0 1-.374-.316zm14.976-7.926L17.284 3.74l-.544 1.887 2.077-.4a.8.8 0 0 1 .84.369.8.8 0 0 1 .034.783L12.9 19.93l-.013.025-.015.023-.122.19a.801.801 0 0 1-.672.37.826.826 0 0 1-.634-.302.8.8 0 0 1-.16-.67l1.029-4.981-1.12.34a.81.81 0 0 1-.86-.262.802.802 0 0 1-.165-.67l.63-3.08-2.027.468a.808.808 0 0 1-.768-.233.81.81 0 0 1-.217-.6l.389-6.57-7.44-1.33a.612.612 0 0 0-.64.906L11.58 23.691a.612.612 0 0 0 1.066-.004l11.26-20.135a.612.612 0 0 0-.644-.9z" />
</svg>
<p className="mt-2 font-medium">Vite</p>
</LinkedCard>

<LinkedCard href="/docs/getting-started/installation/manual">
<svg
  role="img"
  viewBox="0 0 24 24"
  xmlns="http://www.w3.org/2000/svg"
  className="h-10 w-10"
  fill="currentColor"
>
  <title>React</title>
  <path d="M14.23 12.004a2.236 2.236 0 0 1-2.235 2.236 2.236 2.236 0 0 1-2.236-2.236 2.236 2.236 0 0 1 2.235-2.236 2.236 2.236 0 0 1 2.236 2.236zm2.648-10.69c-1.346 0-3.107.96-4.888 2.622-1.78-1.653-3.542-2.602-4.887-2.602-.41 0-.783.093-1.106.278-1.375.793-1.683 3.264-.973 6.365C1.98 8.917 0 10.42 0 12.004c0 1.59 1.99 3.097 5.043 4.03-.704 3.113-.39 5.588.988 6.38.32.187.69.275 1.102.275 1.345 0 3.107-.96 4.888-2.624 1.78 1.654 3.542 2.603 4.887 2.603.41 0 .783-.09 1.106-.275 1.374-.792 1.683-3.263.973-6.365C22.02 15.096 24 13.59 24 12.004c0-1.59-1.99-3.097-5.043-4.032.704-3.11.39-5.587-.988-6.38-.318-.184-.688-.277-1.092-.278zm-.005 1.09v.006c.225 0 .406.044.558.127.666.382.955 1.835.73 3.704-.054.46-.142.945-.25 1.44-.96-.236-2.006-.417-3.107-.534-.66-.905-1.345-1.727-2.035-2.447 1.592-1.48 3.087-2.292 4.105-2.295zm-9.77.02c1.012 0 2.514.808 4.11 2.28-.686.72-1.37 1.537-2.02 2.442-1.107.117-2.154.298-3.113.538-.112-.49-.195-.964-.254-1.42-.23-1.868.054-3.32.714-3.707.19-.09.4-.127.563-.132zm4.882 3.05c.455.468.91.992 1.36 1.564-.44-.02-.89-.034-1.345-.034-.46 0-.915.01-1.36.034.44-.572.895-1.096 1.345-1.565zM12 8.1c.74 0 1.477.034 2.202.093.406.582.802 1.203 1.183 1.86.372.64.71 1.29 1.018 1.946-.308.655-.646 1.31-1.013 1.95-.38.66-.773 1.288-1.18 1.87-.728.063-1.466.098-2.21.098-.74 0-1.477-.035-2.202-.093-.406-.582-.802-1.204-1.183-1.86-.372-.64-.71-1.29-1.018-1.946.303-.657.646-1.313 1.013-1.954.38-.66.773-1.286 1.18-1.868.728-.064 1.466-.098 2.21-.098zm-3.635.254c-.24.377-.48.763-.704 1.16-.225.39-.435.782-.635 1.174-.265-.656-.49-1.31-.676-1.947.64-.15 1.315-.283 2.015-.386zm7.26 0c.695.103 1.365.23 2.006.387-.18.632-.405 1.282-.66 1.933-.2-.39-.41-.783-.64-1.174-.225-.392-.465-.774-.705-1.146zm3.063.675c.484.15.944.317 1.375.498 1.732.74 2.852 1.708 2.852 2.476-.005.768-1.125 1.74-2.857 2.475-.42.18-.88.342-1.355.493-.28-.958-.646-1.956-1.1-2.98.45-1.017.81-2.01 1.085-2.964zm-13.395.004c.278.96.645 1.957 1.1 2.98-.45 1.017-.812 2.01-1.086 2.964-.484-.15-.944-.318-1.37-.5-1.732-.737-2.852-1.706-2.852-2.474 0-.768 1.12-1.742 2.852-2.476.42-.18.88-.342 1.356-.494zm11.678 4.28c.265.657.49 1.312.676 1.948-.64.157-1.316.29-2.016.39.24-.375.48-.762.705-1.158.225-.39.435-.788.636-1.18zm-9.945.02c.2.392.41.783.64 1.175.23.39.465.772.705 1.143-.695-.102-1.365-.23-2.006-.386.18-.63.406-1.282.66-1.933zM17.92 16.32c.112.493.2.968.254 1.423.23 1.868-.054 3.32-.714 3.708-.147.09-.338.128-.563.128-1.012 0-2.514-.807-4.11-2.28.686-.72 1.37-1.536 2.02-2.44 1.107-.118 2.154-.3 3.113-.54zm-11.83.01c.96.234 2.006.415 3.107.532.66.905 1.345 1.727 2.035 2.446-1.595 1.483-3.092 2.295-4.11 2.295-.22-.005-.406-.05-.553-.132-.666-.38-.955-1.834-.73-3.703.054-.46.142-.944.25-1.438zm4.56.64c.44.02.89.034 1.345.034.46 0 .915-.01 1.36-.034-.44.572-.895 1.095-1.345 1.565-.455-.47-.91-.993-1.36-1.565z" />
</svg>
<p className="mt-2 font-medium">Manual</p>
</LinkedCard>

</div>

## Verify [#verify]

### Check the file exists [#check-the-file-exists]

```bash
ls components/ui/bubble.tsx
```

### Import and render it [#import-and-render-it]

```tsx title="bubble.tsx"
import { Bubble, BubbleContent } from "@/components/ui/message";

export default function Page() {
  return (
    <Bubble>
      <BubbleContent>It works.</BubbleContent>
    </Bubble>
  );
}
```

### Confirm no errors [#confirm-no-errors]

If you see `Cannot find module '@/lib/utils'`, run `npx frakment@latest init` again.

## Troubleshooting [#troubleshooting]

<Accordion type="single" collapsible>
<AccordionItem value="styles">
<AccordionTrigger>
Styles do not apply
</AccordionTrigger>

<AccordionContent>
Make sure your globals.css includes the theme tokens from [Theming](/docs/guides/theming).
</AccordionContent>
</AccordionItem>

<AccordionItem value="react-18">
<AccordionTrigger>
Does it work with React 18?
</AccordionTrigger>

<AccordionContent>
Partially. Some components use React 19 features. For React 18, wrap with forwardRef manually.
</AccordionContent>
</AccordionItem>

<AccordionItem value="self-host">
<AccordionTrigger>
Can I self-host the registry?
</AccordionTrigger>

<AccordionContent>
Yes. components.json accepts any registry URL. Point it at https://your-domain.com/r and the CLI will fetch from there.
</AccordionContent>
</AccordionItem>
</Accordion>

## Next [#next]

- [Theming](/docs/guides/theming) - customize tokens and dark mode
- [Components](/docs/components/bubble) - browse the catalog
- [Introduction](/docs) - principles and quick example