# Troubleshooting

Common issues and solutions when using Frontfriend

# Troubleshooting

This guide covers common issues you might encounter when using Frontfriend and how to resolve them.

## Installation Issues

### npm install fails

**Error:** `npm ERR! 404 Not Found - GET https://registry.npmjs.org/@frontfriend%2ftailwind`

**Solution:**
Ensure you're using the correct package name:
```bash
npm install @frontfriend/tailwind@next tw-animate-css
```

### Peer dependency warnings

**Warning:** `npm WARN peer dependency not satisfied`

**Solution:**
Install required peer dependencies:
```bash
npm install -D tailwindcss
npm install tw-animate-css
```

## Configuration Issues

### ff-id not found

**Error:** `Error: ff-id not found in configuration`

**Solutions:**
1. Create `frontfriend.config.js` in your project root:
   ```js
   module.exports = {
     'ff-id': 'your-frontfriend-id'
   }
   ```

2. Check file location - must be in project root, not in src/

3. Verify syntax - use quotes around 'ff-id' key

### Config file not loading

**Error:** `Cannot find frontfriend.config.js`

**Solutions:**
1. For ES modules, use proper export syntax:
   ```js
   export default {
     'ff-id': 'your-id'
   }
   ```

2. For CommonJS, use module.exports:
   ```js
   module.exports = {
     'ff-id': 'your-id'
   }
   ```

## Token Issues

### Styles not applying

**Symptoms:** Design tokens not working, no custom colors available

**Solutions:**
1. Run initialization:
   ```bash
   npx frontfriend init
   ```

2. Check cache status:
   ```bash
   npx frontfriend status
   ```

3. Force refresh:
   ```bash
   npx frontfriend init --force
   ```

4. Restart dev server after init

### Cache expired

**Error:** `Token cache is older than 7 days`

**Solution:**
Tokens auto-refresh after 7 days. Force refresh if needed:
```bash
npx frontfriend init --force
```

### Invalid tokens

**Error:** `Failed to parse design tokens`

**Solutions:**
1. Verify your ff-id is correct
2. Check network connectivity
3. Contact support if issue persists

## Component Issues

### Components not found after download

**Symptom:** Downloaded components but can't import them

**Solutions:**
1. Check download location:
   ```bash
   # Default location based on aliases config
   ls src/components/ui/
   ```

2. Verify import path matches alias:
   ```js
   // If alias is '@/components/ui'
   import { Button } from '@/components/ui/button'
   ```

3. Update TypeScript paths in tsconfig.json:
   ```json
   {
     "compilerOptions": {
       "paths": {
         "@/*": ["./src/*"]
       }
     }
   }
   ```

### Wrong framework components

**Error:** Component syntax doesn't match your framework

**Solution:**
Specify correct framework when downloading:
```bash
# For React
npx frontfriend download button -f react

# For Vue
npx frontfriend download button -f vue
```

### Components overwriting custom code

**Problem:** Downloaded components replaced your modifications

**Solutions:**
1. Back up modified components before downloading
2. Use different output directory:
   ```bash
   npx frontfriend download button -f react -o ./components/frontfriend
   ```
3. Consider extending components instead of modifying

## Build Issues

### Tailwind plugin not working

**Error:** `Cannot find module '@frontfriend/tailwind'`

**Solutions:**
1. Check Tailwind config syntax:
   ```js
   plugins: [
     require('@frontfriend/tailwind')()
   ]
   ```

2. Ensure package is installed:
   ```bash
   npm list @frontfriend/tailwind
   ```

### PostCSS errors

**Error:** `PostCSS plugin tailwindcss requires PostCSS 8`

**Solution:**
Update PostCSS and Tailwind to compatible versions:
```bash
npm update postcss tailwindcss autoprefixer
```

### Vite specific issues

**Error:** `Failed to resolve import`

**Solution:**
Add to vite.config.js:
```js
import frontfriend from '@frontfriend/tailwind/vite'

export default {
  plugins: [frontfriend()],
  resolve: {
    alias: {
      '@': '/src'
    }
  }
}
```

## Network Issues

### Behind corporate proxy

**Error:** `ETIMEDOUT` or `ECONNREFUSED`

**Solution:**
Set proxy environment variables:
```bash
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
npx frontfriend init
```

### API rate limiting

**Error:** `429 Too Many Requests`

**Solution:**
Wait a few minutes before retrying. Tokens are cached for 7 days to minimize API calls.

## Getting Help

If you're still experiencing issues:

1. Check verbose output:
   ```bash
   npx frontfriend init --verbose
   ```

2. Clear cache and retry:
   ```bash
   npx frontfriend clean
   npx frontfriend init
   ```

3. Contact support with:
   - Error message
   - Output of `npx frontfriend status`
   - Your frontfriend.config.js (without ff-id)
   - Framework and version info