Getting Started

Overview

The icondev NPM package is the official SDK for React, Vue, Angular, Svelte, and vanilla JavaScript. Load icons on-demand from Cloudflare CDN with smart caching and full TypeScript support.

Key Features:

• CDN-based loading with smart caching
• React, Vue 3, Angular, Svelte support
• Full TypeScript support
• Works with SSR (Next.js, Nuxt, Remix)
• Lightweight (~5KB core + ~2KB per adapter)

Getting Started

npm install icondev

npx icondev init

import { Icon } from 'icondev/react'

function App() {
  return <Icon name="home" size={24} />
}

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

<template>
  <Icon name="home" :size="24" />
</template>

'use client'

import { Icon } from 'icondev/react'

export default function Page() {
  return <Icon name="home" size={24} />
}

How It Works

1. Run npx icondev init to create icondev.json
2. Import Icon component from icondev/react or icondev/vue
3. Icons load from Cloudflare CDN on first render
4. Cached in memory for instant re-renders
5. In Node.js/SSR: reads from icondev.json
6. In browser: fetches from CDN directly

Basic Usage

React

import { Icon } from 'icondev/react'

<Icon name="home" size={24} />
<Icon name="search" color="blue" />
<Icon name="user" className="my-icon" />

Vue 3

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

<template>
  <Icon name="home" :size="24" />
  <Icon name="search" color="blue" />
  <Icon name="user" class="my-icon" />
</template>

Core API

import { loadIcon, preloadIcons } from 'icondev'

// Load single icon
const { svg } = await loadIcon({ name: 'home' })

// Preload multiple icons
await preloadIcons(['home', 'search', 'user'])

Configuration

After running npx icondev init, you'll have an icondev.json file:

{
  "apiKey": "pk_...",
  "projectSlug": "my-project",
  "cdnUrl": "https://cdn.icon.dev",
  "icons": [
    {
      "slug": "home",
      "name": "Home",
      "url": "https://cdn.icon.dev/...",
      "version": "v1",
      "hash": "abc123"
    }
  ]
}

Updating Icons

When you add new icons to your project, sync your local config:

npx icondev sync

This updates icondev.json with the latest icons from your project.

Available Props

Next Steps

• API Reference - Components, hooks, and functions
• Framework Integration - Next.js, Nuxt, Remix guides
• Best Practices - Performance optimization
• Troubleshooting - Common issues