emoji-datasource-apple

emoji-datasource-apple is one of several platform-specific npm packages published from the emoji-data monorepo (iamcal/emoji-data), the dataset that underpins the emoji pickers used across Slack-style chat apps, editors, and messaging clients. Rather than shipping raw Unicode data alone, this package bundles Apple’s rendered emoji spritesheets at multiple resolutions (16, 20, 32, 64px) together with a JSON index that maps every emoji’s unified codepoint, short name, category, and skin-tone variants to its exact sheet_x/sheet_y coordinates on the sheet.

Consumers install it purely as a data/asset dependency: import emoji.json (or the richer emoji_pretty.json) for lookup metadata, and reference the shipped PNG spritesheets directly for rendering, with ‘clean’ (no-fallback) and quantized (128/256-color) variants available for teams concerned about file size or the licensing of Apple’s original artwork.

What You Get

• Apple emoji spritesheets at 16px, 20px, 32px, and 64px, each with a 1px transparent border per glyph for precise sheet_x/sheet_y cropping
• ‘Clean’ spritesheet variants that omit fallback glyphs, avoiding ambiguity around Apple’s image licensing for missing emoji
• Indexed-color spritesheets (128 and 256 color) for teams that need smaller asset payloads than the full 24-bit sheets
• emoji.json / emoji_pretty.json metadata covering unified codepoints, short names, categories, sort order, and skin-tone variation mappings
• Individual 64px PNGs per emoji (img-apple-64/) for consumers that render single glyphs instead of cropping a shared sheet
• Coverage tracking against the current Unicode Emoji version, updated release-over-release as Apple ships new glyphs in macOS/iOS

Common Use Cases

• Rendering an Apple-style emoji picker in a chat, comment, or messaging product without shipping your own emoji artwork
• Mapping :short_name: colon-syntax input to the correct Apple glyph and sprite position in a text editor or composer
• Building an emoji autocomplete/search feature keyed off category, subcategory, or short-name metadata
• Serving emoji images from a CDN by pointing at the versioned spritesheet paths (e.g. via jsDelivr) instead of bundling every PNG
• Cross-referencing skin-tone variant codepoints for products that support Fitzpatrick modifiers

Under The Hood

Architecture The published npm package is a build artifact of the iamcal/emoji-data monorepo: PHP scripts under build/ (build_image.php, build_map.php, build_catalog.php) consume raw per-vendor image sources and Unicode data files (data_emoji_names_v*.txt, data_variations.txt) to regenerate emoji.json/emoji_pretty.json and the per-platform spritesheets on every Unicode Emoji release. The npm package itself ships no executable code — it is a static bundle of the generated JSON index plus PNG assets, so its ‘architecture’ from a consumer’s perspective is a data contract (fixed JSON schema keyed by unified codepoint) plus a coordinate system (sheet_x/sheet_y against a fixed cell size) rather than any runtime logic.

Tech Stack The generation pipeline is PHP-based (build_*.php, common.php), invoked against raw Unicode data text files and per-vendor source images; the repo also contains a Perl helper (find_missing_summary.php and related). None of this is exposed to or required by npm consumers, whose only dependency surface is static JSON and PNG files declared in package.json’s files array. No build tooling, bundler, or runtime framework is part of the published artifact.

Code Quality There is no test suite in the conventional sense — correctness is enforced by comparing generated sheets/JSON against CHANGES.md-tracked known counts of “missing images” per vendor per Unicode version, and by manual visual review of spritesheets. No CI configuration is present in the repository. This is consistent with a data-generation project rather than an application: the risk surface is data accuracy (correct codepoint-to-image mapping) rather than program logic, and the maintainer has historically caught regressions (e.g. an incorrect Scotland flag, missing non_qualified fields) via community bug reports rather than automated checks.

API Design There is no API surface beyond the JSON schema itself and the documented sprite-coordinate formula (x = sheet_x * (sheet_size + 2) + 1). The schema is stable and well-documented in the README (every field enumerated with its meaning), and the same field names are shared across every platform-specific package (apple/google/twitter/facebook), so a consumer who has integrated one platform’s package can swap to another with no code changes beyond the sheet path. The main ergonomic cost is that consumers must implement their own sprite-cropping and short-name lookup logic — the package provides data, not a rendering component.