# Migration from v1 to v2

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:

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

### Step 2: Update Dependencies

Remove the old package and install the new one:

```bash
# 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:

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

```bash
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:

```diff
/** @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`:

```diff
+ 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`:

```diff
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:

```bash
# 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:
  ```bash
  brew install gsed
  ```


```bash
# 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:

```bash
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

## Common Issues

### Components not found
Ensure your import paths match the `ui` alias in `frontfriend.config.js`.

### Styles not applying
Run `npx frontfriend init --force` to refresh tokens.

### Build errors
Make sure you've updated your Next.js or Vite configuration as shown above.

### Import errors for utils
If you see errors like `@frontfriend/tailwind-config/lib/vue/utils` not found:
- 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:
```bash
brew install gsed
# Then use gsed instead of sed in the commands above
```

## Need Help?

If you encounter issues during migration:
1. Check `npx frontfriend status` output
2. Review the [troubleshooting guide](/docs/legacy/troubleshooting/)
3. Contact support with your migration errors