Troubleshooting

Configuration Issues

"Configuration not found" Error

Symptom: Error when importing icons

Error: icondev.json not found. Run `npx icondev init` to set up the project.

Solution:

npx icondev init

This creates icondev.json with your project configuration and downloads all available icons metadata.

Missing icondev.json File

Symptom: Icons fail to load in Node.js/SSR

Error: Cannot find icondev.json in project root

Solution:

1. Make sure you ran npx icondev init
2. Check that icondev.json exists in your project root
3. Verify the file is not in .gitignore if working with a fresh clone

# Check if file exists
ls -la icondev.json

# If missing, run init
npx icondev init

# If exists but outdated, sync
npx icondev sync

Invalid API Key

Symptom: Init command fails or icons don't load

Error: Invalid API key or unable to fetch project details

Causes:

• Wrong API key format
• API key doesn't have access to project
• Network issues

Solution:

1. Check your API key starts with pk_
2. Verify API key has access to your project in dashboard
3. Re-run init:

npx icondev init

Icons Not Rendering

Check Package Installation

npm list icondev

If not installed:

npm install icondev

Icons Don't Appear

Symptom: No error, but icons don't render

Debugging steps:

1. Check console for errors: Open browser DevTools → Console tab

2. Verify icon name:

   import { getAvailableIcons } from 'icondev'
   console.log(getAvailableIcons())

3. Check icondev.json:

   cat icondev.json

   Make sure it contains your icons array

4. Try preloading:

   import { preloadIcons } from 'icondev'
   await preloadIcons(['home'])

"Icon not found" Error

Symptom: Specific icon fails to load

Error: Icon "my-icon" not found

Solutions:

1. Check icon exists in your project: Visit your Icon.dev dashboard and verify the icon exists

2. Refresh icondev.json:

   npx icondev sync

   Or use npx icondev init to re-initialize from scratch

3. Check icon slug: Icon names are case-sensitive. Use exact slug from dashboard.

Browser Issues

Icons Work in SSR but Not in Browser

Symptom: Icons render during SSR but fail in browser

Cause: Missing IconDevProvider in client-only setup

Solution:

For client-only apps (no SSR), wrap your app with IconDevProvider:

import { IconDevProvider } from 'icondev/react'

const config = {
  apiKey: 'pk_...',
  projectSlug: 'my-project',
  cdnUrl: 'https://cdn.icon.dev'
}

function App() {
  return (
    <IconDevProvider config={config}>
      <YourApp />
    </IconDevProvider>
  )
}

CORS Errors

Symptom: CORS error when loading icons

Access to fetch at 'https://cdn.icon.dev/...' has been blocked by CORS policy

This should NOT happen! Icons are served from public CDN with CORS enabled.

If you see this error:

1. Check if you're behind a proxy/VPN
2. Try disabling browser extensions
3. Contact support at support@icon.dev

Framework-Specific Issues

Next.js: "Module not found" Error

Symptom:

Module not found: Can't resolve 'icondev/react'

Solution:

1. Reinstall package:

   rm -rf node_modules package-lock.json
   npm install

2. Restart Next.js dev server:

   npm run dev

Next.js: Hydration Mismatch

Symptom:

Warning: Text content did not match. Server: "" Client: "<svg>..."

Cause: Icon loads differently on server vs client

Solution:

Use skeleton loading state:

'use client'

import { useState, useEffect } from 'react'
import { Icon } from 'icondev/react'

export function SafeIcon({ name, ...props }) {
  const [mounted, setMounted] = useState(false)

  useEffect(() => setMounted(true), [])

  if (!mounted) {
    return <div className="skeleton w-6 h-6" />
  }

  return <Icon name={name} {...props} />
}

Vue: Icon Not Reactive

Symptom: Changing icon name prop doesn't update the icon

Solution:

The useIcon composable should automatically react to prop changes. If not:

<script setup>
import { watch } from 'vue'
import { Icon, useIcon } from 'icondev/vue'

const props = defineProps<{ name: string }>()

// Force reload on name change
watch(() => props.name, () => {
  // Icon component handles this automatically
})
</script>

<template>
  <Icon :name="name" />
</template>

Performance Issues

Icons Load Slowly

Symptoms:

• Long wait times for icons to appear
• Many network requests

Solutions:

1. Preload critical icons:

   import { preloadIcons } from 'icondev'
   
   // On app mount
   preloadIcons(['logo', 'menu', 'close', 'home'])

2. Check CDN latency: Open DevTools → Network tab → Look for cdn.icon.dev requests

   • Should be < 50ms with CDN caching
   • If slow, might be cold cache (first request)

3. Use loading states:

   import { useIcon } from 'icondev/react'
   
   function MyIcon({ name }) {
     const { svg, loading } = useIcon(name)
   
     if (loading) return <Skeleton />
     return <div dangerouslySetInnerHTML={{ __html: svg }} />
   }

Memory Usage Too High

Symptom: App uses too much memory

Cause: Too many icons cached in memory

Solution:

Clear cache periodically:

import { clearCache } from 'icondev'

// Clear cache when navigating away from icon-heavy page
clearCache()

TypeScript Issues

Type Errors for Icon Names

Symptom:

Type 'string' is not assignable to type 'IconName'

This is a future feature! Currently, icon names are typed as string.

Workaround:

const iconName: string = 'home'
<Icon name={iconName} />

Missing Type Definitions

Symptom:

Could not find a declaration file for module 'icondev'

Solution:

npm install --save-dev @types/node

Or add to tsconfig.json:

{
  "compilerOptions": {
    "skipLibCheck": true
  }
}

Debugging

Enable Debug Mode

Check what's happening under the hood:

1. Check icondev.json:

   cat icondev.json | jq .

2. Verify config in code:

   // Node.js only
   import fs from 'fs'
   const config = JSON.parse(fs.readFileSync('icondev.json', 'utf-8'))
   console.log(config)

3. Test icon loading:

   import { loadIcon } from 'icondev'
   
   loadIcon({ name: 'home' })
     .then(result => console.log('✅ Success:', result))
     .catch(error => console.error('❌ Error:', error))

4. Check available icons:

   import { getAvailableIcons, hasIcon } from 'icondev'
   
   console.log('All icons:', getAvailableIcons())
   console.log('Has "home":', hasIcon('home'))

Verify Configuration

Check that your icondev.json is valid:

1. API Key is correct:

const config = require('./icondev.json')
console.log('API Key:', config.apiKey)
// Should start with 'pk_'

2. Icons array exists:

console.log('Icon count:', config.icons?.length || 0)
console.log('First icon:', config.icons?.[0])

3. CDN URL is accessible:

// Test in browser or Node.js
fetch('https://cdn.icon.dev/health')
  .then(res => console.log('CDN Status:', res.status))
  .catch(err => console.error('CDN Error:', err))

Getting Help

If you're still stuck:

Contact:

• 📧 Email: support@icon.dev
• 📚 Docs: https://icon.dev/docs
• 💬 GitHub: https://github.com/icondev/icondev

Next Steps

• Getting Started - Setup guide
• API Reference - Full API documentation
• Best Practices - Performance tips