Web3Icons

Web3 Icons is a monorepo providing comprehensive cryptocurrency, blockchain, and Web3-related icons as SVGs and React components. The project uses Bun as the package manager and Turbo for build orchestration.

Common Commands

Build Commands

# Build all packages and apps (runs turbo build + post-build)
bun build

# Build only packages (common, core, react)
bun build:packages

# Build individual packages
bun build:common    # Generates metadata TypeScript files from JSON
bun build:core      # Optimizes SVGs, generates index and svg-module
bun build:react     # Generates React components from SVGs

# Build apps
bun build:apps
bun build:website   # Next.js website
bun build:figma     # Figma plugin

# Post-build step (runs after main build)
bun post-build      # Runs generate-icons-md + format

Development

# Start development mode (uses turbo dev)
bun dev

# Format code (Prettier)
bun format

Icon Management

# Add new icons - detects git changes in raw-svgs/
bun add-icons

# Add metadata entry that references existing icons (e.g., testnets, wrapped tokens)
bun add-metadata

# Delete icons and their metadata
bun delete-icons

# Check for missing metadata
bun check-missing

# Validate SVG files
bun validate-svgs
bun validate-filenames

Documentation

# Generate icons documentation (docs/icons.md)
bun generate-icons-md

Publishing

# Sync to CDN (R2)
bun cdn:sync

Architecture

Monorepo Structure

web3icons/
├── packages/
│   ├── common/          # Shared metadata and types
│   ├── core/            # Optimized SVGs
│   └── react/           # React components
├── apps/
│   ├── website/         # Next.js website (web3icons.io)
│   └── figma-plugin/    # Figma plugin
├── scripts/             # Build scripts and CLI tools
└── raw-svgs/            # Source SVG files

Package Dependencies

@web3icons/common: Base package containing metadata (tokens.json, networks.json, wallets.json, exchanges.json) and TypeScript types
@web3icons/core: Depends on common. Contains optimized SVGs in src/svgs/
@web3icons/react: Depends on common. Contains generated React components

Icon Types and Variants

Types: token, network, wallet, exchange

Variants: branded (color), mono (monochrome), background (tokens only)

Build Process Flow

1. Common Package Build

Runs scripts/build-scripts/generate-metadata.ts
Converts JSON metadata files to TypeScript files with type annotations
Located in packages/common/src/metadata/

2. Core Package Build

Pre-build steps (scripts/build-scripts/core/core.pre-build.ts):

Order metadata: Alphabetically sorts all metadata JSON files
Optimize SVGs: Processes raw-svgs/ → packages/core/src/svgs/
- Applies SVGO optimization
- Organizes by type and variant folders
Generate svg-module.ts: Creates import mappings for all SVGs
Generate index.ts: Exports all SVG assets

3. React Package Build

Pre-build steps (scripts/build-scripts/react/react.pre-build.ts):

Generate components: Converts SVGs to React components using SVGR
- Creates Token{Symbol}, Network{Name}, Wallet{Name}, Exchange{Name} components
- Located in packages/react/src/icons/
Generate index.ts: Exports all React components

Icon Workflow

Add SVG files to raw-svgs/{type}/{variant}/ following naming conventions:
- Tokens: UPPERCASE symbol (e.g., BTC.svg)
- Networks/Wallets/Exchanges: kebab-case (e.g., binance-smart-chain.svg)
- SVGs must be 24x24px frames (see CONTRIBUTING.md)
Run bun add-icons:
- Detects git changes in raw-svgs/
- Prompts for metadata (name, id, CoinGecko ID, etc.)
- Adds entries to metadata JSON files
- Or use bun add-metadata to reference existing icons
Build packages:
- bun build:packages processes everything
- SVGs are optimized and copied to core package
- React components are auto-generated

Metadata Structure

Metadata files are the source of truth stored as JSON in packages/common/src/metadata/. They are converted to TypeScript files during the common package build.

Token Metadata (`tokens.json`)

{
  "id": "bitcoin",
  "filePath": "token:BTC",
  "symbol": "BTC",
  "name": "Bitcoin",
  "marketCapRank": 1,
  "addresses": {
    "ethereum": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599",
    "binance-smart-chain": "0x7130d2a12b9bcbfae4f2634d864a1ee1ce3ead9c"
  },
  "variants": ["branded", "mono", "background"]
}

Fields:

id: Unique identifier (typically lowercase with hyphens)
filePath: Icon reference in format type:filename (e.g., token:BTC)
- Icon Sharing System: Multiple entries can reference the same SVG file
- Example: Wrapped tokens can use filePath: "token:ETH" to share Ethereum's icon
- Example: Testnets can use filePath: "network:ethereum" to share mainnet's icon
symbol: Token ticker (uppercase, e.g., BTC, ETH)
name: Full token name
marketCapRank: Market cap ranking (null if not tracked)
addresses: Object mapping network IDs to contract addresses
variants: Array of available icon variants (["branded", "mono", "background"])

Network Metadata (`networks.json`)

{
  "id": "ethereum",
  "filePath": "network:ethereum",
  "chainId": 1,
  "caip2id": "eip155:1",
  "name": "Ethereum",
  "shortName": "ETH",
  "nativeCoinId": "ethereum",
  "variants": ["branded", "mono", "background"]
}

Fields:

id: Network identifier (kebab-case)
filePath: Icon reference (e.g., network:ethereum)
chainId: EVM chain ID (if applicable, can be number or string)
caip2id: CAIP-2 chain ID format (e.g., eip155:1)
name: Full network name
shortName: Abbreviated name
nativeCoinId: Token ID of the native coin
variants: Available icon variants

Wallet Metadata (`wallets.json`)

{
  "id": "metamask",
  "filePath": "wallet:metamask",
  "name": "MetaMask",
  "variants": ["branded", "mono"]
}

Fields:

id: Wallet identifier (kebab-case)
filePath: Icon reference
name: Display name
variants: Available icon variants

Exchange Metadata (`exchanges.json`)

{
  "id": "uniswap",
  "filePath": "exchange:uniswap",
  "name": "Uniswap",
  "type": "dex",
  "variants": ["branded", "mono"]
}

Fields:

id: Exchange identifier (kebab-case)
filePath: Icon reference
name: Display name
type: Either "cex" (centralized exchange) or "dex" (decentralized exchange)
variants: Available icon variants

Key Scripts

scripts/cli/add-icons.ts: Interactive CLI for adding new icons (detects git changes in raw-svgs/)
scripts/cli/delete-icons.ts: Remove icons and metadata
scripts/build-scripts/generate-metadata.ts: Converts JSON metadata → TypeScript with type annotations
scripts/build-scripts/core/core-optimize-svgs.ts: SVG optimization with SVGO + incremental build caching
scripts/build-scripts/core/core-generate-svgs-module.ts: Generates svg-module.ts with all icon imports
scripts/build-scripts/react/react-generate-components.ts: Converts SVGs → React components using SVGR
scripts/maintenance/generate-icons-md.ts: Generates docs/icons.md documentation table
scripts/utils/svg-optimization.ts: SVGO configuration and SVG processing utilities
scripts/utils/build-cache.ts: Incremental build cache system for faster rebuilds

Icon Naming Conventions

File paths (raw-svgs):

raw-svgs/tokens/{variant}/BTC.svg
raw-svgs/networks/{variant}/ethereum.svg
raw-svgs/wallets/{variant}/metamask.svg

React component names:

Tokens: Token{SYMBOL} → TokenBTC, TokenETH
Networks: Network{PascalCase} → NetworkEthereum, NetworkBinanceSmartChain
Wallets: Wallet{PascalCase} → WalletMetamask, WalletRainbow
Exchanges: Exchange{PascalCase} → ExchangeCoinbase, ExchangeBybit

Core SVG exports:

svgs.tokens.brandedBTC (camelCase)
svgs.networks.monoEthereum (camelCase)

Testing Changes

After making changes:

Run bun build:packages to rebuild affected packages
Check generated files:
- packages/common/src/metadata/*.ts
- packages/core/src/svgs/
- packages/react/src/icons/
Run bun format before committing

Important Notes

Always add icons to raw-svgs/ first, never directly to package src folders
The build process is automated - manual edits to generated files will be overwritten
Metadata JSON files in packages/common/src/metadata/ are the source of truth
Use bun add-metadata for entries that share icons with existing entries (e.g., testnets using mainnet icons, wrapped tokens)
SVG optimization happens during core package build, using SVGO with custom config
Incremental builds are enabled by default - only changed SVGs are re-optimized

Advanced Topics

Dynamic React Components

The React package provides dynamic components that automatically load the correct icon based on props. These are client-side only components ('use client' directive) and must be imported from the /dynamic entry point.

TokenIcon Component

import { TokenIcon } from '@web3icons/react/dynamic'

// By symbol
<TokenIcon symbol="ETH" variant="branded" size={32} />

// By contract address + network
<TokenIcon
  address="0xc944e90c64b2c07662a292be6244bdf05cda44a7"
  network="ethereum"
  variant="mono"
  size={32}
/>

// With fallback
<TokenIcon
  symbol="UNKNOWN"
  fallback={<img src="/default.svg" />}
/>

Lookup logic (packages/react/src/utils/find-metadata.ts):

If symbol provided: Case-insensitive match on symbol field
If address + network: Matches contract address in addresses object
Returns ITokenMetadata | undefined

NetworkIcon Component

import { NetworkIcon } from '@web3icons/react/dynamic'

// By name (matches id, name, or shortName - case insensitive)
<NetworkIcon name="Ethereum" variant="branded" size={32} />
<NetworkIcon name="bsc" /> // Matches shortName

// By chainId
<NetworkIcon chainId={1} variant="mono" />

// By CAIP-2 ID
<NetworkIcon caip2id="eip155:1" />

Lookup logic:

If name: Matches against id (kebab-case), name, or shortName (case-insensitive)
If chainId: Exact match on chainId field
If caip2id: Exact match on caip2id field
If id: Matches id or name

WalletIcon & ExchangeIcon

import { WalletIcon, ExchangeIcon } from '@web3icons/react/dynamic'

<WalletIcon name="MetaMask" variant="branded" />
<WalletIcon id="metamask" /> // kebab-case id

<ExchangeIcon name="Uniswap" variant="mono" />

Lookup logic: Case-insensitive match on id (kebab-case) or name

SVG Optimization Details

SVG optimization is handled by scripts/build-scripts/core/core-optimize-svgs.ts using SVGO:

Configuration (scripts/utils/svg-optimization.ts):

removeViewBox: false - Preserves viewBox for proper scaling
prefixIds: true - Prefixes IDs with icon name to prevent conflicts
multipass: true - Multiple optimization passes for better compression
js2svg: { pretty: true } - Pretty-printed output

Optimizations applied:

Remove unnecessary attributes and metadata
Minify paths and transforms
Merge paths where possible
Prefix all IDs to avoid conflicts when multiple SVGs are on the same page
Convert style strings to camelCase objects for JSX compatibility

Incremental Build Cache:

Tracks file hashes to skip unchanged SVGs
Dramatically speeds up rebuilds (only processes modified icons)
Cache stored in node_modules/.cache/web3icons/
Enable with env var or automatically enabled by default

Icon Sharing System (filePath)

The filePath property enables multiple metadata entries to reference the same physical SVG files.

Use cases:

Testnets: Use mainnet icons

{
  "id": "sepolia",
  "filePath": "network:ethereum", // References ethereum.svg
  "name": "Sepolia Testnet",
  "chainId": 11155111
}

Wrapped tokens: Use underlying token's icon

{
  "id": "wrapped-bitcoin",
  "filePath": "token:BTC", // References BTC.svg
  "symbol": "WBTC",
  "name": "Wrapped Bitcoin"
}

Token variants: Multiple listings share same icon

{
  "id": "tether-bridged",
  "filePath": "token:USDT", // References USDT.svg
  "symbol": "USDT.e",
  "name": "Tether USD (Bridged)"
}

Format: {type}:{filename} where:

type: token, network, wallet, or exchange
filename: The SVG filename without extension (e.g., BTC, ethereum, metamask)

TypeScript Types

All metadata types are defined in packages/common/src/types.ts:

type TVariant = 'branded' | 'mono' | 'background'
type TType = 'network' | 'token' | 'wallet' | 'exchange'
type TExchangeType = 'cex' | 'dex'

interface ITokenMetadata {
  id: string
  filePath: string
  symbol: string
  name: string
  marketCapRank: number | null
  addresses: { [key: string]: string | undefined }
  variants: TVariant[]
}

interface INetworkMetadata {
  id: string
  filePath: string
  name: string
  shortName?: string
  nativeCoinId?: string
  chainId?: number | string
  caip2id?: string
  variants: TVariant[]
}

Common Workflows

Adding a New Token with Icon

Create SVG files in raw-svgs/tokens/branded/ and/or raw-svgs/tokens/mono/
- Filename: {SYMBOL}.svg (e.g., BTC.svg, ETH.svg)
- Must be 24x24px frame (see CONTRIBUTING.md)
Run bun add-icons
CLI detects new files and prompts for metadata
Enter token name, ID, contract addresses, etc.
Run bun build:packages to generate components
Verify in packages/core/src/svgs/tokens/ and packages/react/src/icons/tokens/

Adding a Testnet (Reusing Mainnet Icon)

Run bun add-metadata
Select "Network" as the type
Enter icon reference (e.g., network:ethereum)
Provide testnet details (name, chainId, etc.)
Build packages - testnet will use mainnet's icon

Updating Icon Files

Replace SVG in raw-svgs/{type}/{variant}/
Git will show modification
Run bun build:core to re-optimize
Incremental cache detects change and re-processes only that file

Troubleshooting

Icons not showing up after adding:

Ensure bun build:packages was run
Check metadata JSON files in packages/common/src/metadata/
Verify SVG files were copied to packages/core/src/svgs/
Check React components generated in packages/react/src/icons/

Build failing:

Run bun format to fix formatting issues
Check SVG files are valid XML
Ensure metadata JSON files are valid JSON
Check for duplicate IDs in metadata files

Dynamic components not working:

Remember they are client-side only ('use client')
Check lookup logic matches your props (case-insensitive, kebab-case conversions)
Use fallback prop to handle missing icons gracefully

Slow builds:

Incremental cache should be enabled automatically
Clear cache: rm -rf node_modules/.cache/web3icons/
Check if processing all SVGs vs. only changed ones in build output

FilesExpand file tree

AGENTS.md

Latest commit

History

AGENTS.md

File metadata and controls

Web3Icons

Common Commands

Build Commands

Development

Icon Management

Documentation

Publishing

Architecture

Monorepo Structure

Package Dependencies

Icon Types and Variants

Build Process Flow

1. Common Package Build

2. Core Package Build

3. React Package Build

Icon Workflow

Metadata Structure

Token Metadata (tokens.json)

Network Metadata (networks.json)

Wallet Metadata (wallets.json)

Exchange Metadata (exchanges.json)

Key Scripts

Icon Naming Conventions

Testing Changes

Important Notes

Advanced Topics

Dynamic React Components

TokenIcon Component

NetworkIcon Component

WalletIcon & ExchangeIcon

SVG Optimization Details

Icon Sharing System (filePath)

TypeScript Types

Common Workflows

Adding a New Token with Icon

Adding a Testnet (Reusing Mainnet Icon)

Updating Icon Files

Troubleshooting

Token Metadata (`tokens.json`)

Network Metadata (`networks.json`)

Wallet Metadata (`wallets.json`)

Exchange Metadata (`exchanges.json`)