AWS Region Data Without the SDK Tax: A Deep Dive into jsonmaur/aws-regions
Hook
Every AWS SDK weighs in at megabytes of code, but sometimes you just need a lightweight list of region names. That’s the entire premise behind aws-regions, and 129 developers have already found it invaluable.
Context
If you’ve ever built a CLI tool, region selector dropdown, or input validator that needs to know AWS region codes, you’ve faced an annoying choice: either hardcode a region list that goes stale immediately, or import the entire AWS SDK just to enumerate regions. The SDK approach is technically correct but practically absurd—you’re pulling in authentication logic, retry mechanisms, and hundreds of service definitions when all you need is “us-east-1 is called N. Virginia.”
The aws-regions repository solves this with radical simplicity: a single JSON file containing AWS region metadata, maintained by hand, with lightweight library wrappers for Go and JavaScript. It’s the kind of unglamorous infrastructure that makes you wonder why AWS doesn’t provide this as a simple API endpoint. Instead, developers have been copy-pasting region lists from documentation or over-engineering solutions with full SDK imports.
Technical Insight
The architecture is refreshingly straightforward. At the core sits regions.json, a source of truth mapping region codes to human-readable names and availability zone lists. This isn’t dynamically fetched from AWS—it’s a curated dataset that gets updated when maintainers notice new regions launch. A shell script (regions.sh) generates language-specific data files from this master source, keeping Go and JavaScript libraries in sync.
The repository includes libraries for both Go (in the v2 directory) and JavaScript (in the js directory). While the README doesn’t detail the specific API surface, the approach appears to provide access to region metadata through language-appropriate interfaces. The data structure is intentionally minimal—each region entry contains a code (like us-east-1), a name (like N. Virginia), and availability zone identifiers.
What makes this particularly clever is the language-agnostic design. The JSON source file uses a schema that maps naturally to both Go structs and JavaScript objects. When you run ./regions.sh, it regenerates data files for each language binding based on the master JSON. This approach appears designed to minimize runtime overhead by generating static data structures rather than requiring JSON parsing at runtime.
The README calls out three critical caveats that reveal deep AWS knowledge. First, certain regions (us-west-1, ap-northeast-1, sa-east-1) randomize availability zone naming per account—what you see as us-west-1a might map to a different physical datacenter than what another account sees. The README explicitly recommends running aws ec2 describe-availability-zones --region $REGION to verify which zones are available to your specific account. Second, GovCloud regions require special U.S. government agency accounts. Third, China regions are only available to AWS in China accounts. These footnotes prevent developers from building broken assumptions into their tools.
For developers who just need the raw data without any library wrapper, the repository provides direct access to the JSON file at a stable URL. This makes it useful for any language or toolchain.
Gotcha
The elephant in the room is staleness. AWS launches new regions several times per year, and this repository requires manual updates to stay current. As of the README snapshot, there’s a “coming soon” entry for Spain—meaning developers using this library wouldn’t know about that region until the maintainer adds it and you update your dependency. If you’re building infrastructure automation that needs to be region-aware on day one of new launches, this creates a race condition against the maintainer’s attention span.
The availability zone data is particularly tricky. The README explicitly warns that AZ names are randomized per account in certain regions (us-west-1, ap-northeast-1, sa-east-1), rendering the listed zones approximate at best. If you’re using this library to validate user input like “deploy to us-west-1a,” you might reject a perfectly valid AZ for their account or accept one that doesn’t exist for them. The only authoritative source is the AWS EC2 API itself: aws ec2 describe-availability-zones --region $REGION. This library can’t replace that reality.
There’s also no programmatic verification against AWS’s official data sources. The maintainer updates regions.json by hand, presumably by watching AWS announcements and checking documentation. A stale dependency could leave your app showing outdated region lists to users, which is embarrassing in documentation but potentially breaking in validation logic that rejects newly-valid regions.
Verdict
Use if: You’re building CLI tools, documentation generators, or UI components where you need human-readable region names and can tolerate being a few weeks behind AWS announcements. Use if you’re already fighting dependency bloat and importing the full AWS SDK for region enumeration feels absurd. Use if your use case is informational (dropdowns, help text, region selection) rather than mission-critical validation. This library shines in “probably good enough” scenarios where the cost of occasionally missing a brand-new region is lower than the cost of SDK dependencies. The raw JSON file option is particularly useful if you’re working in languages beyond Go and JavaScript. Skip if: You’re building infrastructure automation that must be aware of regions on launch day, if you need account-specific AZ mappings (use the AWS APIs directly), if your application already imports AWS SDKs for other reasons (use their built-in region data instead), or if you need metadata beyond basic region/AZ lists like service availability or regional capacity. The manual maintenance model is this library’s biggest weakness and greatest strength—it’s lightweight because it’s static, but static means stale.
