# Installation

Connect a project, choose your target, and install your first component.

## Before you start

Use Node.js 20 or newer, a working React or Vue application, and Tailwind CSS v4. The React v4 sources target React 19. Create or open a Design System in [Frontfriend](https://app.frontfriend.dev) and copy its `ff-id`.

v4 is currently distributed through the `next` npm tag. The tag and release availability may change at GA; pin the resolved package version in your lockfile.

## 1. Install the package

```bash
pnpm add @frontfriend/tailwind@next tw-animate-css
```

The package includes the `frontfriend` CLI. Use `npm install` instead if your application uses npm.

## 2. Declare your project target

Create `frontfriend.config.js` at the application root:

```js
export default {
  'ff-id': 'YOUR_DESIGN_SYSTEM_ID',
  framework: 'react',
  primitive: 'base',
  aliases: { ui: '@/components/ui' },
};
```

Use `radix`, `base`, or `aria` for React; use `framework: 'vue'` and `primitive: 'reka'` for Vue. Choose one target per application and keep its config, registry namespace and CLI flags aligned. For a CommonJS project, use `module.exports`.

## 3. Initialize tokens

```bash
npx frontfriend init
```

This fetches and caches your Design System. A valid `ff-id` and access to its workspace are required; the command is not an anonymous project generator.

## 4. Connect the build

For Vite, keep your existing framework and Tailwind plugins and add Frontfriend:

```ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';
import frontfriend from '@frontfriend/tailwind/vite';

export default defineConfig({
  plugins: [react(), tailwindcss(), frontfriend()],
});
```

For Vue, replace `react()` with your existing `vue()` plugin. For Next.js, use the wrapper:

```js
import frontfriend from '@frontfriend/tailwind/next';
export default frontfriend({});
```

Import the styles in your application CSS, in this order:

```css
@import "tailwindcss";
@import "@frontfriend/tailwind/theme.css";
@import "tw-animate-css";
```

## 5. Add a component

```bash
npx frontfriend download button -f react --primitive base --registry v4
```

The downloader writes component source into your configured UI directory and reports its dependencies. Review that output and install the required packages. Run your project’s typecheck and build before committing.

```tsx
import { Button } from '@/components/ui/button';

export function Welcome() {
  return <Button variant="main">Make it yours</Button>;
}
```

## Check your setup

```bash
npx frontfriend status
npx frontfriend init --force
```

If a component is unstyled, check the imports, build plugin and cached configuration first. See [Troubleshooting](/docs/troubleshooting/) and [Primitive targets](/docs/primitives/).