Step-by-step guide to migrate from @frontfriend/tailwind-config to @frontfriend/tailwind

Migration Guide: v1 to v2

This guide will help you migrate from @frontfriend/tailwind-config (v1) to @frontfriend/tailwind (v2).

Overview of Changes

Version 2 introduces several improvements:

Simplified package name
New configuration system using frontfriend.config.js
Updated CLI commands
Improved component management

Migration Steps

Step 1: Remove Old UI Components

Delete the existing UI components folder that was managed by v1:

rm -rf src/components/ui
# or
rm -rf components/ui

Step 2: Update Dependencies

Remove the old package and install the new one:

# Remove old package
npm uninstall @frontfriend/tailwind-config
 
# Install new package
npm install @frontfriend/tailwind

Step 3: Create Configuration File

Create frontfriend.config.js in your project root:

// For CommonJS (Next.js)
module.exports = {
  'ff-id': 'your-frontfriend-id',  // Replace with your actual FF ID
  'aliases': {
    'ui': '@/components/ui'  // Where components will be downloaded
  }
}
 
// For ES Modules (Vite)
export default {
  'ff-id': 'your-frontfriend-id',  // Replace with your actual FF ID
  'aliases': {
    'ui': '@/components/ui'  // Where components will be downloaded
  }
}

Step 4: Initialize Design Tokens

Fetch your design tokens using the new CLI:

npx frontfriend init

This replaces the old token fetching mechanism and creates a local cache.

Step 5: Update Tailwind Configuration

Update your tailwind.config.js to use the new plugin:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    // ... your content paths
  ],
  plugins: [
-   require('@frontfriend/tailwind-config')({
-     tokens: './path/to/tokens'
-   })
+   require('@frontfriend/tailwind')()
  ],
}

Step 6: Update Build Configuration

For Next.js

Update next.config.js:

+ const frontfriend = require('@frontfriend/tailwind/next')
 
/** @type {import('next').NextConfig} */
const nextConfig = {
  // Your existing config...
}
 
- module.exports = nextConfig
+ module.exports = frontfriend(nextConfig)

For Vite

Update vite.config.js:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react' // or vue
+ import frontfriend from '@frontfriend/tailwind/vite'
 
export default defineConfig({
  plugins: [
    react(), // or vue()
+   frontfriend()
  ],
})

Step 7: Download Components

Download all available components for your framework:

# For React
npx frontfriend download all -f react
 
# For Vue
npx frontfriend download all -f vue

Component Download Path: Components will be downloaded to the path specified in your frontfriend.config.js aliases. If you have aliases: { ui: '@/components/ui' }, components will be placed in src/components/ui (for Vue) or components/ui (for React). Make sure this directory exists or the downloader will create it.

Step 8: Update Import Statements

Find and replace all imports throughout your codebase:

macOS Users: The default sed command on macOS may encounter encoding issues. We recommend using gsed instead:

brew install gsed

# For macOS (using gsed)
find . -type f \( -name "*.js" -o -name "*.jsx" -o -name "*.ts" -o -name "*.tsx" -o -name "*.vue" \) | xargs gsed -i 's/@frontfriend\/tailwind-config/@frontfriend\/tailwind/g'
 
# For Linux (using sed)
find . -type f \( -name "*.js" -o -name "*.jsx" -o -name "*.ts" -o -name "*.tsx" -o -name "*.vue" \) | xargs sed -i 's/@frontfriend\/tailwind-config/@frontfriend\/tailwind/g'
 
# Or manually search and replace in your IDE:
# Find: @frontfriend/tailwind-config
# Replace: @frontfriend/tailwind

Step 9: Clean Up

Remove the old .npmrc file if it exists:

rm .npmrc

Verification Checklist

After migration, verify that:

npx frontfriend status shows correct configuration
Design tokens are applied (check colors in your app)
Components are downloaded to the correct location
Build process works without errors
Hot reload works in development
No references to @frontfriend/tailwind-config remain

Update the import to @frontfriend/tailwind/lib/vue/utils
Make sure you've run the search/replace command including Vue files

Missing components

Some components are framework-specific. For example, timepicker is only available for Vue. Check the component registry for framework availability.

sed command errors on macOS

If you encounter "illegal byte sequence" errors with sed on macOS, install and use gsed:

brew install gsed
# Then use gsed instead of sed in the commands above

Need Help?

If you encounter issues during migration:

Check npx frontfriend status output
Review the troubleshooting guide
Contact support with your migration errors

Migration from v1 to v2