# components.json

Configuration file for the Frakment CLI.

> 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).

The `components.json` file holds the configuration for the Frakment CLI. `npx frakment init` writes it to your project root. All fields are optional — the defaults match a standard Next.js + Tailwind v4 setup.

## Schema [#schema]

```json title="components.json"
{
  "$schema": "https://www.arrafi.dev/frakment/schema.json",
  "registry": "https://www.arrafi.dev/frakment/r",
  "aliases": {
    "components": "@/components",
    "ui": "@/components/ui",
    "utils": "@/lib/utils"
  },
  "tailwind": {
    "css": "app/globals.css"
  }
}
```

## Fields [#fields]

### `registry` [#registry]

Base URL the CLI fetches components from. Defaults to `https://www.arrafi.dev/frakment/r`.

Override per-command with `--registry <url>`:

```bash
npx frakment add button --registry http://localhost:3000/r
```

### `aliases` [#aliases]

Import path prefixes rewritten in the installed component source. When the CLI writes a file, it replaces `@/components/ui/`, `@/components/`, and `@/lib/utils` with the values here. Match them to your `tsconfig.json` `paths` entries.

| Key | Default | Purpose |
| :-- | :-- | :-- |
| `components` | `@/components` | Top-level components directory |
| `ui` | `@/components/ui` | Component primitive directory |
| `utils` | `@/lib/utils` | `cn()` helper path |

`aliases` controls the **import statements** inside installed files, not where the files are written. Write targets follow the registry payload paths, with a `src/` prefix applied automatically when `tailwind.css` lives under `src/`.

### `tailwind` [#tailwind]

Tailwind v4 entry point. `npx frakment init` injects the theme block into this file.

| Key | Default | Purpose |
| :-- | :-- | :-- |
| `css` | `app/globals.css` | Path to the CSS file that imports Tailwind |

### `platform` [#platform]

Marks the project as a web or Expo project. `init --expo` writes `"platform": "expo"`.

| Value | Purpose |
| :-- | :-- |
| `web` | Default. `add` reads `registry` and `registries.web`. |
| `expo` | `add --expo` reads `registries.expo`. |

### `registries` [#registries]

Optional map of per-platform registry URLs. When present, `add --expo` reads `registries.expo` and `add` reads `registries.web`, falling back to `registry`.

```json
{
  "registries": {
    "web": "https://www.arrafi.dev/frakment/r",
    "expo": "https://www.arrafi.dev/frakment/r/expo"
  }
}
```

The `--registry <url>` flag overrides both maps for that run.

## Minimal setup [#minimal-setup]

```json title="components.json"
{
  "registry": "https://www.arrafi.dev/frakment/r",
  "aliases": {
    "components": "@/components",
    "ui": "@/components/ui",
    "utils": "@/lib/utils"
  },
  "tailwind": {
    "css": "app/globals.css"
  }
}
```

## Troubleshooting [#troubleshooting]

### "CSS file not found: app/globals.css" [#css-file-not-found-appglobalscss]

The path in `tailwind.css` must exist and contain `@import "tailwindcss";`. Create the file first:

```bash
mkdir -p app && echo '@import "tailwindcss";' > app/globals.css
```

### "Component not found in registry" [#component-not-found-in-registry]

The `registry` URL is unreachable. Check connectivity:

```bash
curl <registry>/index.json
```

A `404` means the URL is wrong. A `000` means the host is unreachable.

### Alias mismatch [#alias-mismatch]

If installed files import from `@/components/ui/button` but your project uses `~/ui/button`, adjust `aliases` in `components.json` and re-run `npx frakment add <component> --overwrite`:

```json
{
  "aliases": {
    "components": "~/components",
    "ui": "~/ui",
    "utils": "~/lib/utils"
  }
}
```