elseware-world-data

Typed world metadata and optimized SVG flags for React web, React Native, Expo, SSR, and framework-neutral JavaScript.

Install

npm install elseware-world-data

React Native and Expo consumers also install the renderer peer:

npm install elseware-world-data react-native-svg

Use

import { CountryFlag, Size, getCountry } from "elseware-world-data";

<CountryFlag code="LK" size={Size.md} />;
<CountryFlag code="US" size="lg" shape="rounded" />;

getCountry("lk");

Use a direct flag import when bundle isolation matters:

import { USFlag } from "elseware-world-data/flags/us";

<USFlag size="sm" />;

Bundlers can import the optimized raw SVG:

import usFlagUrl from "elseware-world-data/svg/us";

Core data is available without the component registry:

import {
  countries,
  getCountryByAlpha3,
  searchCountries,
} from "elseware-world-data/data";

import { getCountryDetails } from "elseware-world-data/data/details";

Catalog

npm install
npm run dev

Storybook runs independently at http://localhost:6008. It includes searchable flags, size/ratio/shape controls, metadata inspection, accessibility checks, and special ratio QA.

Development and publishing

Pull requests targeting main run the complete validation suite and verify that the package version has not already been published. A successful merge to main runs the same checks and publishes through GitHub's OIDC trusted publishing; no long-lived npm token is stored in GitHub. Because this source repository is private, npm provenance is disabled.

Configure npm Trusted Publishing for elseware-world-data using repository elsewaretechnology/elseware-world-data, workflow publish.yml, and the GitHub environment npm-production. Keep package.json and package-lock.json synchronized and bump the version in the release PR:

npm version patch --no-git-tag-version

The workflow fails when the exact version already exists on npm. If the repository becomes public, remove --provenance=false to enable provenance.

npm run generate
npm run validate
npm run release

Canonical data and SVGs are vendored in assets; generation and ordinary builds never require network access. Only dist, this README, licenses, and third-party notices enter the npm tarball.

The GitHub Actions release job performs the validated publish automatically after a protected main merge. The local npm run release command remains available for an authenticated release preview or emergency manual operation.

See docs/data-sources.md, docs/political-neutrality.md, and docs/contributing.md for maintenance policy.