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:

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

Peer dependency warnings

Warning: npm WARN peer dependency not satisfied

Solution: Install required peer dependencies:

npm install -D tailwindcss
npm install tw-animate-css

Configuration Issues

ff-id not found

Error: Error: ff-id not found in configuration

Solutions:

Create frontfriend.config.js in your project root:

module.exports = {
  'ff-id': 'your-frontfriend-id'
}

Check file location - must be in project root, not in src/
Verify syntax - use quotes around ‘ff-id’ key

Config file not loading

Error: Cannot find frontfriend.config.js

Solutions:

For ES modules, use proper export syntax:
```
export default {
  'ff-id': 'your-id'
}
```

For CommonJS, use module.exports:

module.exports = {
  'ff-id': 'your-id'
}

Token Issues

Styles not applying

Symptoms: Design tokens not working, no custom colors available

Solutions:

Run initialization:
```
npx frontfriend init
```
Check cache status:
```
npx frontfriend status
```
Force refresh:
```
npx frontfriend init --force
```
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:

npx frontfriend init --force

Invalid tokens

Error: Failed to parse design tokens

Solutions:

Verify your ff-id is correct
Check network connectivity
Contact support if issue persists

Component Issues

Components not found after download

Symptom: Downloaded components but can’t import them

Solutions:

Check download location:

# Default location based on aliases config
ls src/components/ui/

Verify import path matches alias:

// If alias is '@/components/ui'
import { Button } from '@/components/ui/button'

Update TypeScript paths in tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Wrong framework components

Error: Component syntax doesn’t match your framework

Solution: Specify correct framework when downloading:

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

Back up modified components before downloading

Use different output directory:

npx frontfriend download button -f react -o ./components/frontfriend

Consider extending components instead of modifying

Build Issues

Tailwind plugin not working

Error: Cannot find module '@frontfriend/tailwind'

Solutions:

Check Tailwind config syntax:

plugins: [
  require('@frontfriend/tailwind')()
]

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

PostCSS errors

Error: PostCSS plugin tailwindcss requires PostCSS 8

Solution: Update PostCSS and Tailwind to compatible versions:

npm update postcss tailwindcss autoprefixer

Vite specific issues

Error: Failed to resolve import

Solution: Add to vite.config.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:

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:

Check verbose output:
```
npx frontfriend init --verbose
```

Clear cache and retry:

npx frontfriend clean
npx frontfriend init

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