unicode-emoji-json

unicode-emoji-json distills the official Unicode emoji-test.txt data dump into a small set of ready-to-require JSON files, so apps that need emoji metadata (names, categories, versioning, skin tone support) don’t have to parse Unicode’s raw text format themselves. It keeps only RGI (Recommended for General Interchange) emoji, and consolidates each emoji’s five skin tone variants into a single base entry flagged with skin_tone_support, so consumers aren’t stuck de-duplicating near-identical sequences.

The package ships four files tuned for different access patterns — a keyed lookup by emoji character, a grouped-by-category structure, a canonical ordered list, and a small map of skin tone modifier components — plus TypeScript declarations for the two primary exports. There’s no runtime code to execute at all; it’s pure static data plus the build scripts (in script/) that regenerate it from a fresh Unicode data pull whenever a new emoji version ships.

What You Get

• Four ready-to-import JSON files covering per-emoji lookup, per-group categorization, canonical order, and skin-tone-component data
• TypeScript declarations (index.d.ts) describing the dataByEmoji and dataByGroup shapes
• Consolidated skin-tone handling — one base entry per emoji instead of five near-duplicate variant entries
• A repeatable download-and-build pipeline (script/download-unicode-data.js, script/build.js) to regenerate the data against any future Unicode release
• Regression tests (test/test.js) that assert parsed emoji counts against expected totals, catching drift after Unicode version bumps

Common Use Cases

• Populating an emoji picker UI’s category tabs and search index from dataByGroup and dataByEmoji
• Converting between raw emoji characters and GitHub-style :slug: shortcodes using the name/slug fields
• Applying skin tone modifiers correctly in chat or social apps via skin_tone_support flags and data-emoji-components.json
• Filtering emoji by client/platform support using the emoji_version and unicode_version fields

Under The Hood

Architecture There is no runtime execution path at all — package.json’s main field points straight at data-by-emoji.json, so consumers require/import static JSON rather than calling any function. The real architecture lives in the author-time build pipeline: script/download-unicode-data.js pulls the raw emoji-group and emoji-order text dumps from unicode.org, then script/build.js runs two regex-driven parsing passes (a GROUP_REGEX/EMOJI_REGEX pass over the grouped data, an ORDERED_REGEX pass over the ordered data) into in-memory structures before writing out the four shipped JSON files, with script/generate-emoji-counts.js deriving the stats.json used by tests. Because the pipeline relies on module-level mutable state (currentGroup, currentEmoji) and a couple of undeclared variables, the parsing logic is workable but loosely structured rather than cleanly modular.

Tech Stack Plain Node.js CommonJS scripts with zero runtime dependencies — the published package itself needs nothing installed to be consumed. devDependencies are limited to fast-html-parser (for scraping the Unicode data source page) and tape (for the test suite). There’s no bundler, framework, or database involved; the only “deployment” is publishing static JSON files to the npm registry, consumable by any JS/TS runtime that can require or import JSON.

Code Quality test/test.js uses tape to assert that each generated JSON file’s emoji counts match expected totals in test/stats.json, including a dedicated check for the trickier dual-skin-tone combinatorics in the People & Body group — a real if narrow regression-style test that catches undercounting after a Unicode version bump. A GitHub Actions workflow (.github/workflows/test.yml) runs npm ci && npm test on every push and PR. Against that, script/build.js has rougher edges: an implicit global in the slugify loop, an assignment to an undeclared variable, and a bare string thrown instead of an Error object — acceptable for a small internal tool but not polished library code. No linter or formatter config is present in the repo.

API Design The public surface is deliberately minimal: there are no functions or configuration to learn, just JSON files you require directly, so the boilerplate to get started is effectively zero. Field naming is consistent and self-explanatory across all four files (name, slug, group, emoji_version, unicode_version, skin_tone_support). The README documents every file’s exact shape with inline JSON examples. The one rough edge is that index.d.ts declares dataByEmoji/dataByGroup as if they came from a single module entry point, while real usage imports each JSON file by its own path — a minor mismatch that could confuse TypeScript consumers reading the types literally.