`tsx
// LocalizedPrice automatically shows original price if conversion fails
function AutoFallbackPrice() {
return (
basePrice={99.99}
baseCurrency="usd" // Case doesn't matter
apiKey="" // Empty key will show helpful error, then fallback to original price
/>
// If API fails: Shows "$99.99" with tooltip "Conversion failed, showing original price in USD"
)
}

// Or provide custom error component for full control
function CustomErrorPrice() {
return (
basePrice={99.99}
baseCurrency="USD"
// Vite: import.meta.env.VITE_EXCHANGE_API_KEY
// CRA: process.env.REACT_APP_EXCHANGE_API_KEY
// Next.js: process.env.NEXT_PUBLIC_EXCHANGE_API_KEY
apiKey={process.env.REACT_APP_EXCHANGE_API_KEY}
errorComponent={(error) => (


1. Specialized Geolocation Service: ipapi.co
- Why: Dedicated to IP-based location data with HTTPS support for optimal accuracy
- Advantage: No API key required, HTTPS-compatible, robust rate limiting
- Philosophy: Use specialized services for what they do best—identifying location-based data

2. Specialized Financial Data Service: exchangerate-api.com
- Why: Dedicated to currency exchange rates for real-time accuracy
- Advantage: Supports any base currency (not just USD), 1,500 requests/month
- Philosophy: Use specialized services for what they do best—providing currency exchange rates

$3

`bash


.env

`bash


Vite (browser-exposed)

`tsx
import { QueryClient } from '@tanstack/react-query'
import { CurrencyConverterProvider } from 'react-currency-localizer'

// Custom QueryClient with optimized caching strategy
const queryClient = new QueryClient({
defaultOptions: {
queries: {
// Geolocation queries: 24+ hour stale time (location rarely changes)
staleTime: 1000 60 60 * 24, // 24 hours
// Exchange rate queries: 1 hour stale time (balance freshness vs performance)
gcTime: 1000 60 60 * 2, // 2 hours cache time
retry: 1, // Conservative retry to respect API limits
},
},
})

function App() {
return (



)
}
`

> Note: The default configuration already implements the optimal caching strategy. Custom configuration is optional.

⚠️ Important Considerations

$3

When using this library with SSR frameworks (Next.js, Nuxt, SvelteKit), be aware that:

- IP Geolocation runs on the server: The detected location reflects the server's IP, not the user's
- Hydration mismatches possible: Server-rendered currency may differ from client-side detection
- Recommended approach: Pass manualCurrency prop or perform geolocation client-side only

`tsx
// For SSR: Disable geolocation on server, enable on client
const [isClient, setIsClient] = useState(false)

useEffect(() => {
setIsClient(true)
}, [])

return (
basePrice={99.99}
baseCurrency="USD"
apiKey={process.env.NEXT_PUBLIC_EXCHANGE_API_KEY}
manualCurrency={!isClient ? 'USD' : undefined} // Use USD on server, auto-detect on client
/>
)
`

$3

This library uses HTTPS-only APIs (ipapi.co, exchangerate-api.com) to ensure compatibility with secure deployments. Mixed content (HTTP requests from HTTPS sites) is automatically blocked by modern browsers.

$3

While the library has minimal dependencies, it does include:
- @tanstack/react-query (peer dependency for state management)
- @tanstack/query-sync-storage-persister (for localStorage caching)
- @tanstack/react-query-persist-client (for persistence integration)

Total bundle impact: ~27kB minified, ~8.2kB gzipped. Set enablePersistence={false} on the provider to reduce size if persistence isn't needed.

🌍 Supported Currencies

The package supports 161 commonly circulating world currencies via ExchangeRate-API, covering 99% of all UN recognized states and territories.

$3

All ISO 4217 three-letter currency codes are supported, including:

#### Major Global Currencies
- USD - United States Dollar
- EUR - Euro (European Union)
- GBP - Pound Sterling (United Kingdom)
- JPY - Japanese Yen
- CAD - Canadian Dollar
- AUD - Australian Dollar
- CHF - Swiss Franc
- CNY - Chinese Renminbi

#### Popular Regional Currencies
- INR - Indian Rupee
- BRL - Brazilian Real
- RUB - Russian Ruble
- KRW - South Korean Won
- SGD - Singapore Dollar
- HKD - Hong Kong Dollar
- NOK - Norwegian Krone
- SEK - Swedish Krona
- MXN - Mexican Peso
- ZAR - South African Rand
- TRY - Turkish Lira

#### All Supported Currencies


$3

| Code | Currency Name | Country | Reason |
|------|---------------|---------|---------|
| KPW | North Korean Won | North Korea | Due to sanctions & lack of international trade |

> Note: For KPW data, the only reliable source is Daily NK, which reports actual jangmadang market rates via human sources inside DPRK.

$3

The following currencies experience heightened volatility and substantial differences between official and actual exchange rates. Extra caution is recommended:

| Code | Currency Name | Country | Notes |
|------|---------------|---------|-------|
| ARS | Argentine Peso | Argentina | Multiple exchange rates in market |
| LYD | Libyan Dinar | Libya | Political instability affects rates |
| SSP | South Sudanese Pound | South Sudan | High volatility |
| SYP | Syrian Pound | Syria | Ongoing conflict impacts rates |
| VES | Venezuelan Bolívar Soberano | Venezuela | Hyperinflation environment |
| YER | Yemeni Rial | Yemen | Regional instability |
| ZWL | Zimbabwean Dollar | Zimbabwe | Historical hyperinflation legacy |

> Important: For volatile currencies, rates default to central bank published rates, which may differ significantly from actual market rates.

⚡ Performance

- Bundle Size: ~27kB minified, ~8.2kB gzipped
- First Load: 2 API calls (geolocation + exchange rates)
- Subsequent Loads: 0-1 API calls (cached geolocation)
- Cache Duration: 24 hours for geolocation, 1 hour for exchange rates
- Batch Conversion: Convert 1000+ prices in <50ms after initial load
- Memoized Formatters: Intl.NumberFormat instances are cached
- Rate Limits: Handled gracefully with automatic fallbacks

🔍 Troubleshooting

$3

#### "API key is missing" Error
`tsx
// ❌ This will show a helpful error message
useCurrencyConverter({
basePrice: 99.99,
baseCurrency: 'USD',
apiKey: '' // Empty key
})

// ✅ Provide your API key
useCurrencyConverter({
basePrice: 99.99,
baseCurrency: 'USD',
apiKey: process.env.REACT_APP_EXCHANGE_API_KEY
})
`

#### Currency Case Sensitivity
`tsx
// ✅ All of these work the same way (case-insensitive)
useCurrencyConverter({ baseCurrency: 'USD', manualCurrency: 'EUR' })
useCurrencyConverter({ baseCurrency: 'usd', manualCurrency: 'eur' })
useCurrencyConverter({ baseCurrency: 'Usd', manualCurrency: 'Eur' })
`

#### Currency Not Supported Error
`tsx
// If you get: "Currency 'KPW' was detected from your location but is not supported"
// Solution: Use manual currency override (KPW is the only unsupported currency)
useCurrencyConverter({
basePrice: 99.99,
baseCurrency: 'USD',
apiKey: 'your-key',
manualCurrency: 'USD' // Override KPW with a supported currency
})

// For volatile currencies (ARS, VES, etc.), rates may differ from market reality
useCurrencyConverter({
basePrice: 99.99,
baseCurrency: 'USD',
apiKey: 'your-key',
manualCurrency: 'ARS', // Works, but be aware of potential rate discrepancies
onSuccess: (result) => {
console.log('Note: ARS rates may differ from actual market rates')
}
})
`

#### Rate Limiting
`tsx
// The package automatically handles rate limits, but you can also:
useCurrencyConverter({
basePrice: 99.99,
baseCurrency: 'USD',
apiKey: 'your-key',
onError: (error) => {
if (error.message.includes('429')) {
// Handle rate limiting gracefully
console.log('Rate limited, showing original price')
}
}
})
`

🧪 Testing

$3

Run the standard test suite with mocked APIs:

`bash
npm test
`

Run with coverage:

`bash
npm run test:coverage
`

$3

To test with real API calls, first set up your environment:

`bash


Create .env file with your real API key

`bash


Run once with real APIs

`bash


Clone the repository

📜 License

MIT © Jigyansu Rout

✨ Key Design Decisions

This implementation is built on carefully considered architectural choices:

✅ Two-API Architecture - Specialized services for maximum accuracy
✅ TanStack Query Integration - Enterprise-grade state management
✅ Intelligent Caching Strategy - Optimized for each data type
✅ Hook-Based API - Modern React patterns
✅ LocalizedPrice Component - Declarative wrapper component
✅ TypeScript Support - Full type safety and IntelliSense
✅ Free APIs Only - Zero cost barrier to entry
✅ ipapi.co Selection - HTTPS-compatible geolocation service
✅ ExchangeRate-API.com Selection - Reliable currency data provider

🙏 Acknowledgments

- ExchangeRate-API for reliable exchange rate data
- ipapi.co for free HTTPS-compatible IP geolocation services
- TanStack Query for excellent caching and data fetching
- The React community for inspiration and feedback

---

Made with ❤️ for the React community