# Getting Started

Integrate Frontfriend v4 with Tailwind CSS v4

# Getting Started with Frontfriend v4

Frontfriend v4 is the default setup for new projects. It is built for **Tailwind CSS v4** and uses a CSS-first theme file generated from your Frontfriend design system.

Migrating an existing shadcn project? Start with [Migrate from shadcn](/docs/legacy/migrate-from-shadcn/).

Use the v3 guides only for existing Tailwind CSS v3 projects:

- [React + Next.js v3 guide](/docs/legacy/v3/react-setup/)
- [Vue 3 + Vite v3 guide](/docs/legacy/v3/vue-setup/)

## Prerequisites

- A React, Next.js, Vite, or Vue project
- Tailwind CSS v4 already configured in the project
- Node.js 20 or newer recommended
- Your Frontfriend ID (`ff-id`)

## 1. Install Frontfriend v4

v4 is currently published on the `next` npm dist-tag, so install it explicitly:

```bash
npm install @frontfriend/tailwind@next tw-animate-css
```

If you use pnpm:

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

## 2. Add your Frontfriend config

Create `frontfriend.config.js` in your project root:

```js
module.exports = {
  'ff-id': 'your-frontfriend-id-here',
  aliases: {
    ui: '@/components/ui',
  },
};
```

The `ui` alias controls where downloaded components are written.

## 3. Initialize tokens

Fetch your design tokens and prepare Tailwind v4 to use them:

```bash
npx frontfriend init
```

Frontfriend will make your design-system tokens available to Tailwind.

## 4. Import the generated v4 theme

In your app CSS file, import Tailwind first and Frontfriend immediately after it:

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

After this, you can use readable Frontfriend utilities such as `bg-brand-mid`, `text-onbrand-strong`, and `border-neutral-subtle`.

## 5. Add the framework plugin

### Next.js

Wrap your Next.js config with Frontfriend:

```js
// next.config.mjs
import frontfriend from '@frontfriend/tailwind/next';

const nextConfig = {
  // your existing Next.js config
};

export default frontfriend(nextConfig);
```

### Vite

Add the Frontfriend plugin to your Vite config:

```js
// vite.config.js
import { defineConfig } from 'vite';
import frontfriend from '@frontfriend/tailwind/vite';

export default defineConfig({
  plugins: [
    frontfriend(),
    // react(), vue(), or your other plugins
  ],
});
```

Keep your existing React or Vue plugin in the same `plugins` array.

## 6. Download v4 components

For Tailwind v4 projects, use the v4 registry:

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

The v4 React registry currently targets React 19 and only includes migrated v4 components. If a component is not migrated yet, the CLI fails explicitly instead of silently installing a legacy component.

You can also use the shadcn CLI directly against the v4 registry:

```bash
npx shadcn@latest add https://registry.frontfriend.dev/r/v4/react/button.json
```

After installing components, keep `@frontfriend/tailwind/theme.css` imported in your app CSS so the generated Tailwind v4 tokens are available.

## Using tokens

```jsx
export function Example() {
  return (
    <div className="bg-brand-mid text-onbrand-strong rounded-lg p-4">
      <h1 className="text-2xl font-bold">Design system connected</h1>
      <p className="text-onbrand-mid">
        Frontfriend tokens are available as Tailwind v4 utilities.
      </p>
    </div>
  );
}
```

## Common commands

```bash
npx frontfriend init          # Fetch and cache design tokens
npx frontfriend init --force  # Force refresh tokens
npx frontfriend status        # Check config and cache status
npx frontfriend clean         # Clear token cache
```

## Need Tailwind CSS v3?

The old React and Vue setup guides are now grouped under v3:

- [React + Next.js v3 guide](/docs/legacy/v3/react-setup/)
- [Vue 3 + Vite v3 guide](/docs/legacy/v3/vue-setup/)