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.

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

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:

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

If you use pnpm:

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

2. Add your Frontfriend config

Create frontfriend.config.js in your project root:

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:

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:

@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:

// 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:

// 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:

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:

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

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

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: