For the complete documentation index, see 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.
FrakmentFrakment

Installation

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

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

  • 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

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

For all commands, flags, and registry format, see the CLI Reference.

Run init

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

Add components

$ 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/.

Import and use

app/index.tsx
import { Button } from "@/components/ui/button";
 
export default function Screen() {
  return <Button>Save changes</Button>;
}

What you get

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

components.json
utils.ts
theme.ts
  • 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

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

  • clsx
  • tailwind-merge
  • class-variance-authority

Existing Project

Add Frakment to an Expo project you already created.

Configure NativeWind

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.

Copy lib/utils.ts

Copy lib/theme.ts

Create components.json

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"
  }
}

Add a component

$ npx frakment@latest add button --expo

Import and use

app/index.tsx
import { Button } from "@/components/ui/button";
 
export default function Screen() {
  return <Button>Save changes</Button>;
}

Verify

Check the file exists

ls components/ui/button.tsx

Import and render it

app/index.tsx
import { Button } from "@/components/ui/button";
 
export default function Screen() {
  return <Button>Save changes</Button>;
}

Confirm no errors

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

Troubleshooting

init --expo requires expo, react-native, nativewind, and tailwindcss in your package.json. Install them first with npx expo install or npm install.

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.

Motion on native is in progress. Current components use instant state changes, not tweened animation.

npm packages for native components are not published yet. Use the CLI or copy the source from each component page.

Next