Open-Source Databases · annexare

Countries

Countries is a lightweight, well-maintained TypeScript library providing ISO-standard geopolitical and linguistic data (countries, languages, continents, currencies, calling codes). It supports multiple output formats (JSON, CSV, SQL) and works across JavaScript, PHP, and other environments via npm and Composer.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/annexare/Countries

1.3k

GitHub stars

426

Forks

TypeScript

Primary language

MIT

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	annexare/Countries
Owner	annexare
Primary language	TypeScript
License	MIT — OSI-approved
Stars	1.3k
Forks	426
Open issues	12
Latest release	v3.3.0 (2026-03-04)
Last updated	2026-06-14
Source	https://github.com/annexare/Countries

What Countries is

TypeScript-first monorepo (Bun workspaces) exporting strongly-typed ES modules, CommonJS, and IIFE bundles. Data includes ISO 3166-1 (countries), ISO 639-1 (languages), ISO 4217 (currencies with symbols), and ISO 3166-2 continent codes. Provides utility functions for lookups (country by name, code translation, emoji flags) and minimal JSON/CSV subpaths for bundle-size optimization.

Quickstart

Get the Countries source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/annexare/Countries.git2cd Countries3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

International SaaS localization & user data entry

Pre-populate country, language, and currency dropdowns with native names and calling codes; enable name-to-code lookups in multiple languages to reduce data entry friction.

Payment and e-commerce platforms

Integrate ISO 4217 currency metadata (symbols, numeric codes, decimals) with country selection for invoicing, tax compliance, and international checkout flows.

Geographic analytics and reporting dashboards

Enrich data warehouse or BI pipelines with standardized country/continent/language codes and names for filtering, grouping, and multi-language reporting interfaces.

Implementation considerations

Choose import strategy early: subpath imports (e.g., `countries-list/currencies`, `countries-list/minimal`) allow fine-grained bundle control; full imports suit internal tools.
Version 3.x introduced breaking data structure changes; if upgrading from v2, review schema migration (field renaming, type changes) before production rollout.
Leverage TypeScript types (`ICountry`, `TCurrencyCode`) for IDE autocomplete and compile-time safety; ensure team uses a TypeScript-aware build pipeline.
Data is generated from source files in `packages/countries/src`; if you fork or patch, do not edit `dist` directly—rebuild using `bun run build` to avoid desynchronization.
Currency dataset (`packages/countries/src/data/currencies.ts`) is auto-generated from ISO 4217 and Unicode CLDR; regenerate with `bun run generate:currencies` when standards update.

When to avoid it — and what to weigh

Real-time geopolitical or border data required — Library is a static snapshot; does not track diplomatic changes, disputed territories, or currency redenominations in real-time. Manual updates needed for evolving political situations.
Highly customized or proprietary locale rules — Data is standardized to ISO; if your product requires non-standard language/country mappings, timezone handling, or dialect-specific variants, you will need custom layers.
Zero external dependencies in ultra-constrained environments — Requires Node.js/Bun runtime or PHP composer; not suitable for embedded systems, edge devices, or systems with strict supply-chain auditability rules.
Live currency exchange rates or real-time price feeds — Library contains only metadata (name, symbol, decimals); does not include exchange rates, market data, or conversion logic.

License & commercial use

MIT License: permissive, allows commercial use, modification, distribution, and private use without restriction. Requires retention of license and copyright notice in copies or substantial portions.

MIT is a standard, permissive OSI license suitable for commercial projects. No payment, attribution, or licensing agreement required beyond including the original license file. Suitable for closed-source products, SaaS, and embedded use without legal encumbrance.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Adequate
License clarity	Clear
Deployment complexity	Low
DEV.co fit	Strong
Assessment confidence	High

Security considerations

No direct security concerns identified in the library itself. It is a static data module with no network calls, database access, or user input processing. Standard practice: pin version in lockfile to avoid unexpected data changes. Verify data currency if used in compliance/regulatory contexts (e.g., sanctions list validation), as library is manually updated and may lag official ISO/CLDR releases.

Alternatives to consider

i18n-iso-countries

Similar scope (ISO 3166-1, language names), lighter footprint, but less comprehensive currency/calling code data and older v2 API design. Consider if you need minimal country-name localization only.

Rest Countries API (external service)

RESTful service offering similar data (country info, flags, currencies) with real-time updates and no client-side bundle impact. Trade-off: network latency, external dependency, potential service availability risk.

Custom CSV/SQL import

If your data is highly custom or changes frequently, ingest raw ISO 3166/4217 CSVs into your own database and serve via API. Maximizes control but requires maintenance overhead.

Software development agency

Build on Countries with DEV.co software developers

Countries simplifies multi-language, multi-currency product development. Install via npm, import TypeScript types, and enrich user flows with validated, standards-based data.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

world_countries province-city-china atdatabases

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source Databases Web App Development API Development E-commerce Talk to DEV.co

Countries FAQ

Can I use this library in a commercial product?

Yes, MIT license permits unrestricted commercial use. Include the original license file in your distribution and you are compliant.

Will the library automatically update when ISO standards change (e.g., new country codes, currency redenomination)?

No, updates are manual. Maintainers regenerate currency data from official sources, but you must upgrade the package version. Subscribe to releases or review changelogs periodically if currency/country precision is critical.

What is the difference between the main import and minimal subpaths?

Main import (`countries-list`) includes full data with all fields; minimal subpaths (`countries-list/minimal`) provide compact JSON maps (e.g., code-to-name) to reduce bundle size. Use minimal if you only need lookups or offline-first scenarios.

Does this library include real-time exchange rates or geolocation?

No. It provides only metadata (currency names, symbols, ISO codes, country capitals, languages). For exchange rates, geolocation, or live data, integrate a separate service (e.g., Stripe's currency API, ip-geolocation service).

Software development & web development with DEV.co

Need help beyond evaluating Countries? DEV.co is a software development agency offering software development services and web development for teams of every size. Our software developers and web developers build custom software, web applications, APIs, and open-source databases integrations — and maintain them long-term.

Integrate standardized geopolitical data into your platform

Countries simplifies multi-language, multi-currency product development. Install via npm, import TypeScript types, and enrich user flows with validated, standards-based data.

Talk to DEV.co Schedule a Consultation