emojilib

emojilib is a lightweight JSON dataset that maps every standard emoji to an array of searchable English keywords, letting developers build emoji pickers, search bars, and autocomplete features without hand-curating keyword lists themselves. The library ships as a single JSON file (dist/emoji-en-US.json) keyed by emoji character, with each entry holding a canonical slug name plus a set of synonyms and related terms refined through the project’s own scripted review process.

Rather than bundling unicode metadata like grouping, ordering, or skin-tone variants, emojilib stays narrowly scoped to keywords and pairs naturally with the maintainer’s companion package unicode-emoji-json for anyone who needs the fuller emoji dataset. The dataset is maintained through a set of interactive CLI scripts (upgrade, improve, review, augment-en) that let maintainers add, refine, and audit keywords as new emoji revisions are released, with a tape-based test suite verifying every emoji in the Unicode standard has at least one keyword entry before each release.

What You Get

• A single JSON dataset (dist/emoji-en-US.json) mapping every standard emoji to a slug name plus keyword synonyms
• TypeScript type declarations (dist/index.d.ts) for typed access to the keyword map
• Interactive maintainer scripts (upgrade, improve, review, augment-en) for keeping keywords current with new emoji releases
• A tape-based test suite that verifies every emoji in the Unicode standard has keyword coverage before each release

Common Use Cases

• Building an emoji picker’s search-as-you-type filtering
• Powering :keyword: to emoji autocomplete in chat and comment editors
• Adding emoji search to a Slack/Discord-style reaction picker
• Tagging or classifying user content by mapping emoji to semantic keywords

Under The Hood

Architecture emojilib is about as minimal architecturally as a package gets: there’s no runtime module, no exported functions or classes beyond a single default export. Its main entry (dist/emoji-en-US.json) is a static object keyed by emoji character, valued by an array of keyword strings, and that same checked-in file is what maintainers edit directly rather than compiling from a separate source of truth. On the maintainer side, scripts/upgrade.js, improve.js, review.js, and augment-en.js form an interactive pipeline that mutates the dataset in place as new Unicode emoji revisions land, keeping content and distribution artifact one and the same. Because the API surface is just a keyed lookup table, the only real “breakage” risk is a shape change to the object itself, not any internal implementation complexity.

Tech Stack The package is plain CommonJS JavaScript with a hand-written TypeScript declaration file (dist/index.d.ts) rather than a TypeScript source build. Its devDependencies (tape for testing, promptly for interactive CLI prompts, change-case, emoji-platform-data, fast-xml-parser) exist entirely to support the maintainer-only scripts, not the published artifact itself. There is no bundler or build step — dist/ is committed directly to the repository and published as-is via npm.

Code Quality The only test file, scripts/test.js, uses tape to assert that dist/emoji-en-US.json contains a keyword array for every code point in the sibling unicode-emoji-json package’s ordered emoji list — a coverage check rather than unit tests of logic, reflecting how little executable logic the package actually contains. A GitHub Actions workflow (.github/workflows/test.yml) runs npm ci && npm test on every push. There’s no linter config, though a prettier.config.js enforces formatting on the small set of maintainer scripts.

API Design Consumers get a single default export: a plain object keyed by the emoji character itself, valued as an array of keyword strings, requiring zero configuration and zero boilerplate to use. TypeScript users get accurate typing for free via the shipped .d.ts. The v4 rewrite deliberately dropped the previous major version’s nested {keywords, char, fitzpatrick_scale, category} shape in favor of this flatter one, moving unicode metadata to the sibling unicode-emoji-json package — a clean separation of concerns that keeps this package’s API to a single job (keyword search) at the cost of a second install for consumers who also want full emoji metadata, a tradeoff the README’s migration guide documents clearly.