Installation

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 and copy its ff-id.

Every project starts from a Design System. There are no registry-only operations without an ff-id. When a project has no ff-id, init, migrate, update, download and the other Design System commands check that first. They stop, explain how to create or connect a Design System, and do not change the project.

The current release is 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

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:

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.

You can also let the CLI write this file. Sign in, then connect the Design System:

npx frontfriend login
npx frontfriend setup --ff-id YOUR_DESIGN_SYSTEM_ID --framework react --primitive base

In an existing shadcn project, setup stops after connecting and tells you to run migrate before init. See Adopt Frontfriend.

3. Initialize tokens

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:

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:

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

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

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

5. Add a component

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.

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

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

Check your setup

npx frontfriend status
npx frontfriend init --force

If a component is unstyled, check the imports, build plugin and cached configuration first. See Troubleshooting and Primitive targets.