# flagpack-core is the SVG asset layer under the React, Vue and Svelte flag packages

> Flagpack's core package holds 250+ flag icons, the ISO 3166 based country list and the generator scripts that turn a spreadsheet into optimised SVG assets. Since version 2.0.0 every flag is imported separately so bundlers can drop what you do not use.

**Yummygum/flagpack-core** — Flagpack contains 250+ flag icons to easily use within your code project.

- Repository: https://github.com/Yummygum/flagpack-core
- Website: https://flagpack.xyz
- Stars: 651 · Forks: 130
- Language: TypeScript
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/yummygum-flagpack-core

## The core package is the asset layer, not the component

Flagpack is described as a set of 250+ flag icons for use in a code project, published as open source with framework packages for React, Vue and Svelte. The repository you are looking at is flagpack-core, and its own description explains what it is for: it has been created to provide and share the flag assets used in Flagpack, and it also provides some logic to help with building on top of the package, for example mapping over the countryCodeList.json to display all flags. The distribution model follows from that. When you install the React, Vue or Svelte package, the core is pulled in automatically as a peer dependency, which is why the documentation for installing flagpack-core talks about setting it up by cloning the repository rather than adding it to your dependency list. Anyone who wants to check the asset source, tweak a flag or work on the generators is working in this repository, while application developers are consuming it through a wrapper.

## Since 2.0.0 every flag is a separate import

The change that most affects a consuming application is the one described under Use. With the release of Flagpack 2.0.0, the package no longer serves all of the images in a single file, and the stated reason is to only serve the flags it requires, in other words to perform treeshaking. The consequence is that you have to import each flag separately, using the flags directory in flagpack-core, and the documentation points at the react-flagpack package for an example of how to set this up dynamically. For a bundle conscious team this is the whole point: the set is no longer a single blob that your bundler cannot analyse. For a developer used to importing a component and getting every variant with it, the change is friction, and the migration from a 1.x style import is something to plan for rather than discover. The flagpack-core package itself is version 2.1.0 in its manifest, and it publishes a types entry at lib/index.d.ts, so the TypeScript types ship with the package.

## ISO 3166 is the baseline, and the exceptions are documented

Which flags to include is described as an ongoing point of discussion, and the project resolves it with a rule. As of the 2.0 release Flagpack uses the ISO 3166 standard as its baseline for flag selection, meaning it provides flags for all ISO 3166 countries. ISO 3166 specifies countries, and that produced two exceptions, both of which the project handles by using the ISO 3166-2 subsets. The first is the BES islands. The Islands of Saba, Saint Eustatius and Bonaire are their own entity within the ISO standard but do not have a shared flag, so they are included individually under the alpha-2 codes BQ-SA, BQ-BO and BQ-SE. The second is the countries within the United Kingdom. To give a clear distinction between them, the flags of England, Scotland, Wales and Northern Ireland are included alongside the flag of the UK itself, which uses the alpha-2 code GB-UKM, with the four using GB-ENG, GB-SCT, GB-WLS and GB-NIR. For anything that is a country or location but sits outside ISO 3166, the answer is no, and the project is explicit that it offers no guarantees about which flags will be added in future versions.

## Regenerating the assets needs a spreadsheet key and an API key

The build section is where the project stops being a drop-in dependency and becomes a pipeline. To build the generateCodeList.js script and make the request to the Google API that fetches the flag data, you need an .env file with a SPREADSHEET_KEY and an API_KEY. There is a documented shortcut: if you only want to make changes to generateFlags.js, the .env is not needed, and you can just use the current countryCodeList.json. That file is committed to the repository, so the country list is source data rather than something every build must fetch. The build itself is three commands:

```bash
# install dependencies
npm install

# build for prod
npm run build

# build with watcher for dev
npm run dev
```

This is a real constraint on the project and worth naming plainly. The asset pipeline is anchored to an external spreadsheet and an external API, so a change on the other side of that API can break regeneration for everyone, and a contributor who only wants to touch the flag generation can avoid it entirely by working from the committed list. For an evaluator this is the single most important operational fact about the repository.

## The build is a chain of generators, not a bundler call

The package.json scripts show what the build actually does. The build command runs four steps in sequence: build:generateTypes, build:generateFlags, build:optimizeFlags and build:code, and the last of those is tsc. The three generator steps run ts-node-dev scripts from the cli directory, namely cli/generateTypes.ts, cli/generateFlags.ts and cli/optimizeFlags.ts, each with the same flags for no notifications, respawn and transpile only. In other words, the shipped library is produced by code generation plus a TypeScript compile, and the generators are part of the source rather than a one off script. The dependency list supports that reading: svgo and its types for SVG optimisation, papaparse for parsing the spreadsheet data, node-fetch for the API call, ora for progress output and dotenv for the .env file. The repository also carries a rollup.config.js and a .babelrc, plus src/, lib/, svg/ and cli/ directories and types.d.ts at the root.

## Local testing uses npm link rather than a workspace

Testing the core locally is done by linking it, and the documentation explains why. Normally, if you use any of the framework components, the core will be installed automatically as a peer dependency. To test the core itself you need to install one of the components and install the core as a local module, which starts with:

```bash
$ git clone https://github.com/Yummygum/flagpack-core
$ cd ./flagpack-core
$ npm link
```

Then, in your test project, you install the local dependency with:

```bash
$ npm link flagpack-core
```

The documentation points at the npm link documentation for the mechanics. This is an old but perfectly serviceable approach, and it has one consequence worth knowing: a linked package is resolved from your local filesystem rather than the registry, so a change in the core shows up in the consuming app without a publish step, and a forgotten unlink can leave a project pointing at a directory that no longer exists. If you are on a modern toolchain, a workspace arrangement does the same job with less manual state, but nothing in the documentation requires you to move away from this one.

## Releasing is a manual three step sequence

The release procedure is documented to the same level of detail as the build, which is a good sign for a package whose framework siblings depend on it. First all changes have to be committed and pushed, and you decide on a release type, which the documentation lists as patch at 0.0.1, minor at 0.1.0 or major at 1.0.0. Then you bump the version, which updates the version number in package.json and adds a git tag automatically:

```bash
npm version <release_type>
```

Next you push the tag to the remote:

```bash
git push --tags origin master
```

And after that you publish to npm:

```bash
npm publish
```

Finally, when you are confident with the release, you make sure the version tag is also released on GitHub. That last step is manual and is the kind of thing that gets forgotten, which matters if you consume this package by GitHub release rather than by version range. The release history shows why that matters here. Version 1.1.2 was published on 2021-04-20, version 2.0.0 on 2021-08-04 and version 2.1.0 on 2025-12-01, so the treeshaking rewrite was a long time ago and the most recent release is recent, while the last push to the repository was on 2026-06-18.

## Where flagpack-core is the wrong tool

The boundary is scope, and it is a deliberate one. Because the selection rule is ISO 3166 countries and locations, the set will never contain the flag of an organisation, a union, a historic state or a sub-national unit outside the ISO 3166-2 subsets, and the project says outright that it makes no guarantees about future additions. If you need those, this package is the wrong source and you are looking for a broader icon set instead. The second limit is the dependency chain. Consuming the flags through a framework package means taking the core as a peer dependency and, with the 2.0.0 change, importing each flag separately, which is more work at the call site than a single import. The third is the regeneration path, which depends on a Google API and a spreadsheet key that the project controls and you do not. None of these make the package bad, but each one is a decision to make before you adopt it rather than after. The licence is MIT with a LICENSE file at the root, which is about as permissive as it gets for vendoring the assets into a product.

## Conclusion

Adopt flagpack-core if you want a maintained set of country flags with per-flag imports that a bundler can shake, and if your product ships React, Vue or Svelte front ends. Do not adopt it if you need flags outside the ISO 3166 country set, or if you intend to regenerate the assets yourself without a Google API key and a spreadsheet. Before you start, decide whether you want the framework wrappers or the raw assets in the svg directory, read the flag policy so your country list matches, and check that the last push on 2026-06-18 is recent enough for the release you intend to pin.

## FAQ

### How do I install flagpack-core?

Normally the core is installed automatically as a peer dependency of the framework packages for React, Vue or Svelte, so you do not install it directly. If you want to work on the core itself you clone the repository with git clone https://github.com/Yummygum/flagpack-core.

### Why do I have to import each flag separately in flagpack-core?

Since version 2.0.0 the package no longer serves all images in a single file, so that only the flags you require are served, which the documentation calls treeshaking. You import each flag from the flags directory, and the react-flagpack package shows how to set that up dynamically.

### Which countries does flagpack-core include flags for?

Flagpack uses ISO 3166 as its baseline and provides flags for all ISO 3166 countries, with two documented exceptions. The BES islands are included individually as BQ-SA, BQ-BO and BQ-SE, and the flags of England, Scotland, Wales and Northern Ireland are included as GB-ENG, GB-SCT, GB-WLS and GB-NIR alongside the UK flag GB-UKM.

### What do I need to build the flagpack-core assets?

An .env file with a SPREADSHEET_KEY and an API_KEY, so the generateCodeList.js script can request the flags data from the Google API. If you only want to change generateFlags.js, the .env is not needed because you can use the current countryCodeList.json.

## Sources

- [License: MIT](https://github.com/Yummygum/flagpack-core/blob/main/LICENSE)
- [Project website](https://flagpack.xyz)
- [README](https://github.com/Yummygum/flagpack-core/blob/main/README.md)
- [Releases](https://github.com/Yummygum/flagpack-core/releases)
- [Yummygum/flagpack-core on GitHub](https://github.com/Yummygum/flagpack-core)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/yummygum-flagpack-core