# Installation

How to install Frakment components in a React Native project via Expo.

> 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="native" customBases={[{"href":"/docs/getting-started/installation","name":"web","title":"Web"},{"href":"/docs/getting-started/installation/native","name":"native","title":"Native"}]} />

Frakment native components are built for React Native apps that run on iOS and Android via Expo. There are two paths: use the CLI with `--expo` to fetch components from the registry, or copy the source files manually.

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

- A working `components.json` with `platform: "expo"` and `registries.expo`
- `lib/utils.ts` and `lib/theme.ts`
- Three dependencies installed via `npx expo install`: `clsx`, `tailwind-merge`, `class-variance-authority`
- Your first native component installed and rendering

## Prerequisites [#prerequisites]

- **Node.js** 18 or newer
- **Expo SDK** 58 or newer
- **React Native** 0.88
- **NativeWind** 5.0.0-rc or newer
- **Tailwind CSS** v4
- **TypeScript** (recommended)
- A stylesheet that imports `nativewind/theme`, such as `global.css` or `app/global.css`

Components target Expo SDK 58 and React Native 0.88. Older versions may need manual adjustments.

### Additional peer packages [#additional-peer-packages]

Some components need extra peers. Install them with the component:

- `react-native-reanimated` 4.7 or newer
- `react-native-safe-area-context` 5.10 or newer
- `react-native-svg` 15.16 or newer
- `react-native-gesture-handler` 3.3 or newer
- `react-native-worklets`
- `lucide-react-native`
## 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 --expo
```

Verifies the required dependencies, detects your NativeWind stylesheet, writes `components.json` with `platform: "expo"` and `registries.expo`, copies `lib/utils.ts` and `lib/theme.ts`, and installs 3 dependencies via `npx expo install`: `class-variance-authority`, `clsx`, `tailwind-merge`.

<Step>
Add components
</Step>

```bash
npx frakment@latest add button --expo
```

Fetches `button.json` from the Expo registry, resolves registry dependencies recursively, resolves npm dependencies, writes source into `components/ui/`.

<Step>
Import and use
</Step>

```tsx title="app/index.tsx"
import { Button } from "@/components/ui/button";

export default function Screen() {
  return <Button>Save changes</Button>;
}
```
</Steps>

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

After `frakment init --expo`, your project will have:

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

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

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

- **`components.json`** - `platform`, `registries`, `aliases`, and `tailwind.css`. Read by the CLI on every `add`.
- **`lib/utils.ts`** - `cn()` helper for merging NativeWind classes.
- **`lib/theme.ts`** - `useThemeColors()` hook and the `ThemeColors` type used by every native component.

### Dependencies [#dependencies]

`frakment init --expo` checks your `package.json` and installs any missing package via `npx expo install`:

- `clsx`
- `tailwind-merge`
- `class-variance-authority`
## Existing Project [#existing-project]

Add Frakment to an Expo project you already created.

<Steps>
<Step>
Configure NativeWind
</Step>

Follow the NativeWind 5 setup guide. Wrap `metro.config.js` with `withNativeWind` and confirm `global.css` imports `tailwindcss/theme.css`, `tailwindcss/utilities.css`, and `nativewind/theme`.

<Step>
Copy `lib/utils.ts`
</Step>

<ComponentSource src="../../apps/native/lib/utils.ts" title="lib/utils.ts" />

<Step>
Copy `lib/theme.ts`
</Step>

<ComponentSource src="../../apps/native/lib/theme.ts" title="lib/theme.ts" />

<Step>
Create `components.json`
</Step>

```json title="components.json"
{
  "platform": "expo",
  "registry": "https://www.arrafi.dev/frakment/r",
  "registries": {
    "web": "https://www.arrafi.dev/frakment/r",
    "expo": "https://www.arrafi.dev/frakment/r/expo"
  },
  "aliases": {
    "components": "@/components",
    "ui": "@/components/ui",
    "utils": "@/lib/utils"
  },
  "tailwind": {
    "css": "global.css"
  }
}
```

<Step>
Add a component
</Step>

```bash
npx frakment@latest add button --expo
```

<Step>
Import and use
</Step>

```tsx title="app/index.tsx"
import { Button } from "@/components/ui/button";

export default function Screen() {
  return <Button>Save changes</Button>;
}
```
</Steps>

## Verify [#verify]

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

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

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

```tsx title="app/index.tsx"
import { Button } from "@/components/ui/button";

export default function Screen() {
  return <Button>Save changes</Button>;
}
```

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

If you see `Cannot find module '@/lib/utils'`, run `npx frakment@latest init --expo` again.
## Troubleshooting [#troubleshooting]

<Accordion type="single" collapsible>
<AccordionItem value="preflight">
<AccordionTrigger>
Preflight checks failed
</AccordionTrigger>

<AccordionContent>
`init --expo` requires `expo`, `react-native`, `nativewind`, and `tailwindcss` in your `package.json`. Install them first with `npx expo install` or `npm install`.
</AccordionContent>
</AccordionItem>

<AccordionItem value="stylesheet">
<AccordionTrigger>
Could not find the NativeWind stylesheet
</AccordionTrigger>

<AccordionContent>
`init --expo` looks for `global.css`, `app/global.css`, `src/global.css`, `src/app/global.css`, or `styles/global.css`. Create one that imports `tailwindcss/theme.css`, `tailwindcss/utilities.css`, and `nativewind/theme`.
</AccordionContent>
</AccordionItem>

<AccordionItem value="motion">
<AccordionTrigger>
No animation on native
</AccordionTrigger>

<AccordionContent>
Motion on native is in progress. Current components use instant state changes, not tweened animation.
</AccordionContent>
</AccordionItem>

<AccordionItem value="npm-publish">
<AccordionTrigger>
No npm package for native
</AccordionTrigger>

<AccordionContent>
npm packages for native components are not published yet. Use the CLI or copy the source from each component page.
</AccordionContent>
</AccordionItem>
</Accordion>

## Next [#next]

- [Button](/docs/components/native/button) - the first native component
- [Theming](/docs/guides/theming) - customize tokens
- [CLI Reference](/docs/libraries/cli) - all commands and flags