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

Peer dependency warnings

Warning: npm WARN peer dependency not satisfied

Solution: Install required peer dependencies:

npm install -D tailwindcss postcss autoprefixer

Configuration Issues

ff-id not found

Error: Error: ff-id not found in configuration

Solutions:

1. Create frontfriend.config.js in your project root:

   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:

   export default {
     'ff-id': 'your-id'
   }

2. 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:

1. Run initialization:

   npx frontfriend init

2. Check cache status:

   npx frontfriend status

3. Force refresh:

   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:

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:

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

2. Verify import path matches alias:

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

3. 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:

1. Back up modified components before downloading
2. Use different output directory:

   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:

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

2. 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:

1. Check verbose output:

   npx frontfriend init --verbose

2. Clear cache and retry:

   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