# @russian-flags/republics-of-ussr
[Русская версия](./README.md)
A native ESM collection of SVG flags and metadata for the union republics of the USSR. It follows the structure of other `@russian-flags` packages: standalone SVG assets, typed metadata, name lookup, and lazy flag loaders.
The collection is based on the Russian Wikipedia page [“List of Union Republics of the USSR”](https://ru.wikipedia.org/wiki/%D0%A1%D0%BF%D0%B8%D1%81%D0%BE%D0%BA_%D1%81%D0%BE%D1%8E%D0%B7%D0%BD%D1%8B%D1%85_%D1%80%D0%B5%D1%81%D0%BF%D1%83%D0%B1%D0%BB%D0%B8%D0%BA_%D0%A1%D0%A1%D0%A1%D0%A0): the 15 republics present from 1956 to 1991, plus the Karelo-Finnish SSR as a historical sixteenth entry.
## Collection
| No. | Flag | Republic | slug | Union-republic period |
| ---: | --- | --- | --- | --- |
| 1 | 
| Russian SFSR | `russian-sfsr` | 1922–1991 |
| 2 | 
| Ukrainian SSR | `ukrainian-ssr` | 1922–1991 |
| 3 | 
| Byelorussian SSR | `byelorussian-ssr` | 1922–1991 |
| 4 | 
| Uzbek SSR | `uzbek-ssr` | 1925–1991 |
| 5 | 
| Kazakh SSR | `kazakh-ssr` | 1936–1991 |
| 6 | 
| Georgian SSR | `georgian-ssr` | 1936–1991 |
| 7 | 
| Azerbaijan SSR | `azerbaijan-ssr` | 1936–1991 |
| 8 | 
| Lithuanian SSR | `lithuanian-ssr` | 1940–1991 |
| 9 | 
| Moldavian SSR | `moldavian-ssr` | 1940–1991 |
| 10 | 
| Latvian SSR | `latvian-ssr` | 1940–1991 |
| 11 | 
| Kirghiz SSR | `kirghiz-ssr` | 1936–1991 |
| 12 | 
| Tajik SSR | `tajik-ssr` | 1929–1991 |
| 13 | 
| Armenian SSR | `armenian-ssr` | 1936–1991 |
| 14 | 
| Turkmen SSR | `turkmen-ssr` | 1925–1991 |
| 15 | 
| Estonian SSR | `estonian-ssr` | 1940–1991 |
| — | 
| Karelo-Finnish SSR | `karelo-finnish-ssr` | 1940–1956, historical |
The first 15 entries follow the order in Article 71 of the 1977 Constitution of the USSR. The historical republic is appended last.
## Features
- 16 production-ready optimized SVG files exported through `flags/` and `svg/`.
- Native ESM build with TypeScript declarations.
- A lazy module loader for every flag.
- Lookup by slug, code, short/full name, or alias.
- Period, status, and constitutional-order metadata.
## Installation
```bash
npm install @russian-flags/republics-of-ussr
```
For a local check from another project:
```bash
npm install /path/to/republics-of-USSR
```
## Quick start
```js
import { loadFlag, republics } from "@russian-flags/republics-of-ussr";
console.log(republics[0]);
// {
// slug: "russian-sfsr",
// code: "RUSSIAN_SFSR",
// nameRu: "Российская СФСР",
// nameEn: "Russian SFSR",
// fullNameRu: "Российская Советская Федеративная Социалистическая Республика",
// fullNameEn: "Russian Soviet Federative Socialist Republic",
// aliases: ["РСФСР", "Россия", "Russia", "RSFSR"],
// unionFrom: 1922,
// unionTo: 1991,
// constitutionalOrder: 1,
// status: "constituent-1991",
// }
const image = await loadFlag("RSFSR", {
alt: "Flag of the Russian SFSR",
className: "flag",
});
document.body.append(image);
```
`loadFlag` is an alias for `loadFlagImage`. Both functions target browsers and require a global `Image`/DOM. Metadata and lookup helpers work in Node.js.
## Direct SVG imports
```js
import russianFlag from "@russian-flags/republics-of-ussr/flags/russian-sfsr";
import ukrainianSvg from "@russian-flags/republics-of-ussr/svg/ukrainian-ssr.svg";
console.log(russianFlag);
console.log(ukrainianSvg);
```
Both paths resolve to `dist/flags/.svg`. Importing an SVG as a module requires an asset-aware bundler such as Vite, webpack, or Parcel.
After publication, assets can also be served through an npm CDN:
```html
```
## Republic lookup
```js
import {
normalizeRepublicInput,
republicSlugs,
resolveRepublicSlug,
} from "@russian-flags/republics-of-ussr";
console.log(republicSlugs.length); // 16
console.log(resolveRepublicSlug("RUSSIAN_SFSR")); // "russian-sfsr"
console.log(resolveRepublicSlug("РСФСР")); // "russian-sfsr"
console.log(resolveRepublicSlug("Russia")); // "russian-sfsr"
console.log(resolveRepublicSlug("КФССР")); // "karelo-finnish-ssr"
console.log(resolveRepublicSlug("unknown")); // undefined
console.log(normalizeRepublicInput(" UKRAINIAN_SSR ")); // "ukrainian-ssr"
```
Input is trimmed and lowercased; `ё` is treated as `е`, and spaces or underscores become hyphens.
## API
| Export | Description |
| --- | --- |
| `republics` | `RepublicMeta` metadata array. |
| `republicSlugs` | Array of every available slug. |
| `normalizeRepublicInput(input)` | Normalizes user input. |
| `resolveRepublicSlug(input)` | Resolves a slug from a code, name, or alias. |
| `getFlagModuleLoader(input)` | Returns a lazy loader or `undefined`. |
| `loadFlagModule(input)` | Lazily imports a flag module. |
| `loadFlagImage(input, options)` | Creates an `HTMLImageElement` for a flag. |
| `loadFlag(input, options)` | Alias for `loadFlagImage`. |
| `preloadFlag(input)` | Starts loading a module without awaiting it. |
| `createFlagImage(src, defaultAlt, options)` | Creates and configures an `![]()
`. |
Core types: `RepublicSlug`, `RepublicInput`, `RepublicStatus`, `RepublicMeta`, `FlagImageOptions`, and `FlagModule`.
## Working with SVG assets
1. Open `assets//index.svg`.
2. Make the required changes to the source flag SVG.
3. Keep `xmlns="http://www.w3.org/2000/svg"` and a scalable `viewBox`.
4. Run `npm test`.
Files in `assets` are the package sources. The build copies them into `dist/flags/.svg`; do not edit `dist` manually.
## Demo
```bash
npm install
npm --prefix examples install
npm run example:dev
```
The demo installs `@russian-flags/republics-of-ussr` from npm, reads the collection from the `republics` export, and lazily loads each SVG through `loadFlagModule`. It does not access the local `assets` directory directly.
## Development
```bash
npm run build
npm test
npm run typecheck
npm run pack:dry
```
`scripts/build-source.js` reads `src/republics.ts`, validates `assets//index.svg`, and generates types and loaders. `scripts/build.js` builds JavaScript and copies SVG files into `dist`.
## Repository
- GitHub:
- Issues:
## License
Package code is MIT-licensed. Historical symbols and final flag assets may be regulated separately; see [LICENSE](./LICENSE).