Emojibase regenerates its emoji datasets from the Unicode source files

What the packages are and what they are generated from

Emojibase describes itself as a collection of lightweight, up-to-date, pre-generated, specification compliant, localized emoji JSON datasets, regex patterns, and more, and the homepage banner calls it the ultimate emoji database.

The word that matters in that sentence is generated. The README states that the datasets are built directly from the emoji data source files published by Unicode, and that the project is based on the official Unicode Technical Standard #51, with localization provided by Unicode Technical Standard #35.

So there are three inputs and three outputs. The inputs are the raw Unicode emoji data files, the CLDR annotation data that carries the localized keywords, and the two technical standards that define how the data should be interpreted. The outputs are JSON datasets, shortcode mappings, regex patterns and generated TypeScript types, packaged across several npm packages.

The release tags show the shape of the publishing. The recent versions are [email protected], [email protected] and [email protected], all dated 2026-10-16, and the version number tracks the release the data was generated against rather than a semver sequence of the library's own API.

The README is also explicit about version currency. It supports the latest Emoji 18, Unicode 18 and CLDR 49 release versions, and those three numbers are the ones a consumer should check before shipping, because an emoji picker that is two Unicode versions behind is missing entire scripts and flag combinations that users will search for.

The generation pipeline in the root package.json

The repository is a yarn workspace with lerna.json, a .yarn directory and a .changeset directory, and the root package.json documents the whole pipeline in its scripts. It is worth reading, because the generation steps are the project's real specification.

    "build": "tsdown --workspace",
    "generate:emojis": "rm -rf ./cache/final && node ./bin/generateEmoji.mjs",
    "generate:po": "node ./bin/generatePo.mjs",
    "generate:regex": "node ./bin/generateRegex.mjs",
    "generate:shortcodes": "node ./bin/generateShortcodes.mjs",
    "generate:types": "node ./bin/generateTypes.mjs",
    "test": "jest --colors --logHeapUsage",
    "type": "tsc --build"

There is one script per output artefact, and each lives in the bin directory. generateEmoji.mjs produces the emoji datasets and starts by clearing the cache/final directory, generatePo.mjs produces the localization files from the po directory of gettext catalogues, generateRegex.mjs produces the regex patterns, generateShortcodes.mjs produces the shortcode mappings, and generateTypes.mjs produces the TypeScript type definitions.

The composite generate script chains the emoji and shortcode steps, then runs a separate script to build a file size table, then generates the tests. That file size table is a detail that tells you something real about the project's priorities: the datasets are large, and the maintainer wanted the size of each artefact to be visible in the repository rather than discovered by a user.

The test generation step copies three files from the English data package into the test-utils package, the data.json, the shortcodes file and the messages file, so that the test utilities carry their own fixture copy rather than importing from the data package.

The engines field requires node >=22.18.0, which is a real constraint for a project that only produces data files, and it is the clearest signal of the toolchain cost.

The conformance test, which is the part to watch

Among the scripts there is one that stands out, because it tells you how the project defends its claim of being specification compliant.

    "test:conformance:update": "UPDATE_CONFORMANCE_BASELINE=1 jest packages/data/tests/conformance.test.ts",

There is a conformance test inside the data package that runs against a baseline, and updating that baseline is an explicit, separate operation gated by an environment variable. A baseline is a record of what the data looked like when it was last accepted, and a test that compares current output to it detects unintended drift.

This matters more here than it would in most projects, because the alternative to generating the data is a hand-maintained table that silently goes stale. A conformance baseline means a change in the upstream Unicode files shows up as a diff, and someone decides whether to accept it.

The rest of the tooling is conventional. Tests run under jest with the logHeapUsage flag, which matters for a project that loads large JSON files into memory. Types are checked with tsc --build, formatting is prettier, linting is eslint over the package sources and tests and the website source, and the check script runs type, then test, then lint. The build uses tsdown across the workspace, and the release script packs, generates and then publishes through changesets, which is the versioning tool the .changeset directory belongs to.

There is also a website directory with its own start script for the documentation site, and the docs command runs it.

What the monorepo contains and how the packages divide up

The repository top level shows a workspace with a packages directory, and the release tags name three of those packages, which is the clearest available evidence of the split: emojibase for the data itself, emojibase-regex for the search patterns, and emojibase-test-utils for the helper package that other projects use to assert against the datasets.

The test-utils package exists because the data is only useful if something verifies against it. A common pattern in an emoji picker is to show a search result only when the typed text matches a shortcode or a localized keyword, and the test utilities are what a consuming project uses to check that its search behaviour agrees with the dataset.

Around the packages are the supporting directories. The po directory holds the gettext translation catalogues that the localization step reads. The bin directory holds the generation scripts. The types directory holds the generated type definitions. There is a docs directory, a website directory for the documentation site, a tests directory at the root, and a CHANGELOG.md and LICENSE.

The npm dependency picture is visible in the badges and the root manifest. The core package is on npm as emojibase, and the data package emojibase-data is tracked on jsDelivr with a badge for its hits, which is a hint that the data package is the one people fetch at runtime, for example to serve a picker to a browser, while the core package is the one a bundler consumes at build time.

The primary language is TypeScript, the licence is MIT, and the repository is not archived with the last push on 2026-10-16, the same day as the 18.0.0 releases.

Where Emojibase is the wrong tool

Three limits, and the first is about scale.

The first is that the whole toolchain is disproportionate for a single lookup. The README describes the datasets as lightweight, and they are, relatively, but the machinery that produces them is a yarn workspace with lerna, tsdown, jest, eslint, prettier, changesets, a Babel config, a tsdown config and a Node 22 requirement, plus a generation step that fetches Unicode source files and runs eight separate scripts. If your application needs one emoji's shortcode and its keywords, that is a lot of project for one record, and the sensible alternative is to read the JSON out of the published package and stop there.

The second is that the data is a snapshot, and the snapshot is what the whole design is about. The version numbers 18.0.0 refer to a specific Emoji, Unicode and CLDR triple, and a consumer who ships a picker needs to know when that data was generated. New emoji, new flag sequences, new skin tone combinations and new localized keywords all arrive with the upstream releases, and none of them appear in a package until the maintainer regenerates. For a product that markets itself on up-to-date emoji, that lag is the thing to measure, and the README's claim of supporting the latest releases is a claim about the current build, not a promise about the next one.

The third is that the localization surface is broad and therefore a maintenance commitment for whoever depends on it. The CLDR annotations that supply localized keywords are numerous, and a consumer who offers an interface in twenty languages is trusting twenty keyword sets that were machine-translated upstream rather than written by the project. The README is honest that the localization comes from Technical Standard #35, which is the right place to get it from, but it does not describe any review of those translations.

The alternative approach is to consume the upstream files directly. Unicode publishes the emoji data and CLDR publishes the annotations, and a project with unusual needs, for example a fixed set of emoji in one language, or a data format the published packages do not offer, could run its own generation. The difference in approach is that Emojibase has already made the decisions about shortcodes, about which languages to include, about the JSON shape and about the regex format, and it maintains a conformance baseline so that those decisions are visible when the upstream data moves.

Editorial conclusion

Adopt Emojibase if you need emoji data with shortcodes, localized keywords, skin tone variants and search regexes that stay in step with the current Unicode and CLDR releases, because the datasets are generated from the source files rather than curated by hand. Do not adopt it if you need a single emoji lookup table, since the generation pipeline, the yarn workspace and the Node 22 requirement are a lot of machinery for one lookup, and do not rely on it as a source of truth for the latest Unicode release without checking which release it was generated against. Verify first that the package version you install matches the Unicode, Emoji and CLDR versions your product targets, that the locale coverage in the package includes the languages your interface offers, and that the conformance test in the repository passes for the data version you depend on, since the repository carries a separate script for updating that baseline.

Frequently asked questions

Official sources

1. License: MIT
2. milesj/emojibase on GitHub
3. Project website
4. README
5. Releases