{"id":32368936,"url":"https://github.com/dr5hn/countrystatecity","last_synced_at":"2025-10-24T19:36:37.336Z","repository":{"id":318447330,"uuid":"1071322866","full_name":"dr5hn/countrystatecity","owner":"dr5hn","description":"Official Country State City - NPM Packages","archived":false,"fork":false,"pushed_at":"2025-10-22T15:21:02.000Z","size":9420,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-22T17:24:51.060Z","etag":null,"topics":["cities","city","countries","country","nodejs","npm","package","state","states"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@countrystatecity/countries","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dr5hn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-07T07:31:40.000Z","updated_at":"2025-10-18T13:12:09.000Z","dependencies_parsed_at":null,"dependency_job_id":"33449542-96e6-4576-a8bf-2ee415398c52","html_url":"https://github.com/dr5hn/countrystatecity","commit_stats":null,"previous_names":["dr5hn/world"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/dr5hn/countrystatecity","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dr5hn%2Fcountrystatecity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dr5hn%2Fcountrystatecity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dr5hn%2Fcountrystatecity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dr5hn%2Fcountrystatecity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dr5hn","download_url":"https://codeload.github.com/dr5hn/countrystatecity/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dr5hn%2Fcountrystatecity/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280857007,"owners_count":26403190,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-24T02:00:06.418Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cities","city","countries","country","nodejs","npm","package","state","states"],"created_at":"2025-10-24T19:36:36.311Z","updated_at":"2025-10-24T19:36:37.325Z","avatar_url":"https://github.com/dr5hn.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @countrystatecity/* Package Ecosystem\n\n[![CI](https://github.com/dr5hn/countrystatecity/workflows/CI/badge.svg)](https://github.com/dr5hn/countrystatecity/actions/workflows/ci.yml)\n[![Data Update](https://github.com/dr5hn/countrystatecity/workflows/Update%20Data/badge.svg)](https://github.com/dr5hn/countrystatecity/actions/workflows/update-data.yml)\n\nOfficial package ecosystem for countries, states, cities, and geographic data with iOS/Safari support and minimal bundle sizes.\n\n## 📦 Packages\n\n### @countrystatecity/countries [![npm](https://img.shields.io/npm/v/@countrystatecity/countries)](https://www.npmjs.com/package/@countrystatecity/countries)\n\nComplete countries, states, and cities database with lazy loading and iOS compatibility.\n\n- **Location:** [`packages/countries`](./packages/countries)\n- **Documentation:** [README](./packages/countries/README.md)\n- **Bundle Size:** \u003c10KB initial load\n- **Data:** 250+ countries, 5,000+ states, 150,000+ cities\n- **Environment:** 🖥️ **Server-side only** (Node.js, Next.js API routes, Express, etc.)\n- **Status:** ✅ Implemented\n\n```bash\nnpm install @countrystatecity/countries\n```\n\n\u003e **⚠️ Server-Side Only**: This package requires Node.js file system access. For browser/frontend use, see [@countrystatecity/countries-browser](#countrystatecitycountries-browser) (coming soon).\n\n### @countrystatecity/timezones [![npm](https://img.shields.io/npm/v/@countrystatecity/timezones)](https://www.npmjs.com/package/@countrystatecity/timezones)\n\nComprehensive timezone data with conversion utilities and iOS compatibility.\n\n- **Location:** [`packages/timezones`](./packages/timezones)\n- **Documentation:** [README](./packages/timezones/README.md)\n- **Bundle Size:** \u003c20KB initial load\n- **Data:** 392 IANA timezones, 223 countries, 131 abbreviations\n- **Environment:** 🖥️ **Server-side only** (Node.js, Next.js API routes, Express, etc.)\n- **Status:** ✅ Implemented\n\n```bash\nnpm install @countrystatecity/timezones\n```\n\n### @countrystatecity/countries-browser\n\nBrowser-compatible version of the countries package for frontend/client-side usage.\n\n- **Location:** TBD\n- **Documentation:** [Specification](./specs/4-countries-browser-package-spec.md)\n- **Bundle Size:** ~75KB gzipped for typical use\n- **Data:** Same as server package (250+ countries, 5,000+ states, 150,000+ cities)\n- **Environment:** 🌐 **Browser/Frontend** (React, Vue, Svelte, Vite, etc.)\n- **Status:** 📋 Planned (see [Issue #17](https://github.com/dr5hn/countrystatecity/issues/17))\n\nThis package will provide fetch-based data loading for browser environments with the same API as the server package.\n\n## 🚀 Quick Start\n\n\u003e **💡 Choose the right package for your environment:**\n\u003e - **Server-side** (Node.js, Next.js API routes, Express): Use `@countrystatecity/countries`\n\u003e - **Browser/Frontend** (React, Vue, Svelte, Vite): Use `@countrystatecity/countries-browser` (coming soon) or create API endpoints\n\n### Countries, States, and Cities (Server-Side)\n\n```typescript\nimport { getCountries, getStatesOfCountry, getCitiesOfState } from '@countrystatecity/countries';\n\n// Get all countries (lightweight - ~5KB)\nconst countries = await getCountries();\n\n// Get states for a country\nconst states = await getStatesOfCountry('US');\n\n// Get cities in a state\nconst cities = await getCitiesOfState('US', 'CA');\n```\n\n### Timezones\n\n```typescript\nimport { getTimezones, getTimezonesByCountry, convertTime } from '@countrystatecity/timezones';\n\n// Get all timezones\nconst timezones = await getTimezones();\n\n// Get timezones for a country\nconst usTimezones = await getTimezonesByCountry('US');\n\n// Convert time between timezones\nconst converted = await convertTime(\n  '2025-10-18 14:00',\n  'America/New_York',\n  'Asia/Tokyo'\n);\n```\n\n## ✨ Key Features\n\n- 📱 **iOS Compatible**: No stack overflow errors on Safari/iOS browsers\n- 🚀 **Minimal Bundle**: \u003c10KB initial load with lazy loading\n- 🔄 **Dynamic Loading**: Uses dynamic imports for code-splitting\n- 🌐 **Full Data**: Countries, states, cities with translations\n- ⏰ **Timezone Support**: Comprehensive timezone information\n- 📝 **TypeScript**: Full type definitions included\n- 🔧 **Tree-Shakeable**: Only bundle what you use\n\n## 🎯 Why This Ecosystem?\n\n### The Problem\n\nThe popular `country-state-city` package (162K weekly downloads) has critical issues:\n\n- 🔴 8MB bundle size (includes ALL data upfront)\n- 🔴 iOS Safari crashes with stack overflow errors\n- 🔴 Unmaintained for 2+ years\n- 🔴 Static imports force entire bundle inclusion\n\n### Our Solution\n\n- ✅ Minimal bundle (\u003c10KB initial)\n- ✅ Dynamic imports \u0026 lazy loading\n- ✅ iOS/Safari compatible\n- ✅ Always updated from authoritative database\n- ✅ Tree-shakeable \u0026 code-splittable\n\n### Bundle Size Comparison\n\n| Action | @countrystatecity/countries | country-state-city |\n|--------|----------------------------|-------------------|\n| Install \u0026 import | 5KB | 8MB |\n| Load countries | +2KB | - |\n| Load US states | +30KB | - |\n| Load CA cities | +15KB | - |\n| **Total for typical use** | **~50KB** | **8MB** |\n\n**160x smaller bundle size!**\n\n## 📊 Package Comparison\n\n### Server vs Browser Packages\n\n| Feature | @countrystatecity/countries | @countrystatecity/countries-browser |\n|---------|----------------------------|-------------------------------------|\n| **Environment** | Node.js, Bun, Deno | Browser, Frontend |\n| **Data Loading** | File system (`fs`) | Fetch API |\n| **Dependencies** | Node.js built-ins | Zero |\n| **Initial Bundle** | ~15KB | ~15KB + 130KB countries data |\n| **Lazy Loading** | ✅ Via file system | ✅ Via HTTP requests |\n| **TypeScript** | ✅ | ✅ |\n| **Same API** | ✅ | ✅ |\n| **Use Cases** | Next.js API routes, Express, serverless functions | React, Vue, Svelte, vanilla JS |\n| **iOS Compatible** | ✅ | ✅ |\n| **Caching** | OS file cache | HTTP cache + memory |\n| **Status** | ✅ Available now | 📋 Planned |\n\n### When to Use Each Package\n\n**Use `@countrystatecity/countries` (Server) when:**\n- ✅ Building API endpoints or backends\n- ✅ Using Next.js App Router server components\n- ✅ Running in Node.js, serverless functions (Vercel, AWS Lambda)\n- ✅ You have file system access\n- ✅ Building command-line tools\n\n**Use `@countrystatecity/countries-browser` (Browser) when:**\n- ✅ Building client-side React/Vue/Svelte apps\n- ✅ Using Vite for frontend development\n- ✅ Need to load data in the browser directly\n- ✅ Building single-page applications (SPAs)\n- ✅ Running in browser environments only\n\n**Current Workaround (until browser package is ready):**\nCreate API endpoints using the server package, then fetch from your frontend:\n\n```typescript\n// pages/api/countries.ts (Next.js API route)\nimport { getCountries } from '@countrystatecity/countries';\n\nexport default async function handler(req, res) {\n  const countries = await getCountries();\n  res.json(countries);\n}\n\n// components/CountrySelector.tsx (Frontend)\nconst countries = await fetch('/api/countries').then(r =\u003e r.json());\n```\n\nSee [Vite Deployment Guide](./docs/VITE_DEPLOYMENT.md) for detailed patterns.\n\n## 🏗️ Monorepo Structure\n\n```\ncountrystatecity/\n├── .github/\n│   └── workflows/          # CI/CD workflows\n│       ├── ci.yml          # Continuous Integration\n│       ├── update-data.yml # Automated data updates\n│       └── publish.yml     # NPM publishing\n├── packages/\n│   └── countries/          # @countrystatecity/countries package\n├── specs/                  # Technical specifications\n├── package.json            # Root package configuration\n└── pnpm-workspace.yaml     # Workspace configuration\n```\n\n## 🔄 CI/CD \u0026 Automation\n\n### Continuous Integration\nEvery push and PR automatically:\n- ✅ Runs type checking\n- ✅ Executes 42 comprehensive tests\n- ✅ Builds all packages\n- ✅ Validates bundle sizes\n- ✅ Tests iOS/Safari compatibility\n\n### Automated Data Updates\nWeekly automated updates (Sundays at 00:00 UTC):\n- 📥 Downloads latest data from [source repository](https://github.com/dr5hn/countries-states-cities-database)\n- 🔄 Transforms into optimized split structure\n- 🧪 Runs full test suite\n- 📝 Creates PR for review if changes detected\n\n**Manual trigger:** Go to [Actions](https://github.com/dr5hn/countrystatecity/actions/workflows/update-data.yml) → Run workflow\n\n### Publishing\nAutomated publishing to NPM on version changes:\n- 🔍 Detects version bumps in package.json\n- 📦 Builds and tests before publishing\n- 🚀 Publishes to NPM registry\n- 🏷️ Creates GitHub release with changelog\n\nSee [Workflow Documentation](./.github/workflows/README.md) for details.\n\n## 🛠️ Development\n\n### Prerequisites\n\n- Node.js \u003e= 18.0.0\n- pnpm \u003e= 8.0.0\n\n### Setup\n\n```bash\n# Install dependencies\npnpm install\n\n# Build all packages\npnpm build\n\n# Run tests\npnpm test\n\n# Run tests in watch mode\ncd packages/countries \u0026\u0026 pnpm test:watch\n```\n\n### Commands\n\n```bash\n# Build all packages\npnpm build\n\n# Test all packages\npnpm test\n\n# Clean build artifacts\npnpm clean\n```\n\n## 📊 Testing\n\nAll packages include comprehensive tests:\n\n- ✅ Unit tests\n- ✅ Integration tests\n- ✅ iOS/Safari compatibility tests\n\nCurrent coverage: 42 tests passing\n\n## 📖 Documentation\n\n- [Monorepo Plan](./specs/1-monorepo-plan.md)\n- [@countrystatecity/countries Spec](./specs/2-world-countries-npm-package-spec.md)\n- [Package Ecosystem Spec](./specs/3-world-package-ecosystem-spec.md)\n\n## 🤝 Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n**For data-related issues** (incorrect country names, missing cities, wrong coordinates, etc.), please report them to the [Countries States Cities Database](https://github.com/dr5hn/countries-states-cities-database/issues) repository, which is the source of data for this package.\n\n## 📄 License\n\n[ODbL-1.0](./LICENSE) © [dr5hn](https://github.com/dr5hn)\n\nThis package and its data are licensed under the Open Database License (ODbL) v1.0. The data is sourced from the [Countries States Cities Database](https://github.com/dr5hn/countries-states-cities-database) which is also licensed under ODbL-1.0.\n\nYou are free to share, create, and adapt this database as long as you:\n- **Attribute**: Credit the original sources\n- **Share-Alike**: Distribute adaptations under the same license\n- **Keep Open**: Don't use technical restrictions\n\n## 🔗 Links\n\n- [GitHub Repository](https://github.com/dr5hn/countrystatecity)\n- [Issues](https://github.com/dr5hn/countrystatecity/issues)\n- [NPM Organization](https://www.npmjs.com/org/countrystatecity)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdr5hn%2Fcountrystatecity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdr5hn%2Fcountrystatecity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdr5hn%2Fcountrystatecity/lists"}