Emojibase

Common errors

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use ES module `import` syntax in a CommonJS (CJS) file or environment without proper transpilation or configuration.
  fix Ensure your `package.json` includes `"type": "module"` if you are writing an ESM project. If you must use CommonJS, use dynamic `import('emojibase')` or configure a bundler like Webpack/Rollup to handle ESM imports.

• Error: Emojibase requires Node.js v18.12.0 or higher.

  cause Running Emojibase v16 or newer on an unsupported Node.js version (e.g., v16 or older).
  fix Update your Node.js installation to version 18.12.0 or newer to meet the minimum engine requirements for Emojibase.

• TypeError: Cannot read properties of undefined (reading 'find')

  cause Trying to access methods on an undefined emoji dataset, potentially due to incorrect import paths or a failed data load.
  fix Verify that `getEmojiData` is correctly imported and awaited, and that the returned data is not `null` or `undefined`. Check for any network issues if loading data remotely, or ensure `emojibase-data` is properly installed if using local data files.

Warnings

• breaking Emojibase v17.0.0 updates its internal data to the latest Emoji v17 and CLDR 48 specifications. While mostly backwards compatible, changes in emoji properties or the introduction/removal of certain emojis might affect applications relying on specific data points or subset IDs.
  Fix: Review your emoji processing logic to ensure compatibility with Emoji v17 and CLDR 48. Test any filtering or lookup mechanisms against the new dataset.
• breaking Version 16.0.0 of Emojibase dropped support for Node.js v16. Projects must now run on Node.js v18.12.0 or higher.
  Fix: Upgrade your Node.js environment to version 18.12.0 or newer. Ensure your CI/CD pipelines and deployment environments are also updated.
• breaking Emojibase has transitioned to an ESM-first package, particularly since v16. While CJS might still function in some setups, direct `require()` calls for modern features or in pure ESM projects may fail.
  Fix: Prefer `import` statements for Emojibase modules. If you are in a CommonJS environment, consider configuring your project for hybrid ESM/CJS or using dynamic `import()` for Emojibase.

Install

• npm install emojibase npm
• yarn add emojibase yarn
• pnpm add emojibase pnpm

Imports

• getEmojiData
  wrong:

  const { getEmojiData } = require('emojibase');

  correct:

  import { getEmojiData } from 'emojibase';

  Emojibase is primarily an ESM package since v16. Use `import` syntax. `getEmojiData` is a common utility to retrieve emoji datasets.
• getEmojiRegex
  wrong:

  import { getEmojiRegex } from 'emojibase';

  correct:

  import { getEmojiRegex } from 'emojibase-regex';

  Emoji regex utilities are provided by the separate `emojibase-regex` package, not the core `emojibase` package itself. Ensure you install and import from the correct package.
• Emoji

  import type { Emoji } from 'emojibase';

  Type import for the Emoji interface when working with TypeScript.

Quickstart

Demonstrates fetching all emoji data, finding a specific emoji, and using the emoji regular expression to match emojis within a string.

import { getEmojiData } from 'emojibase';
import { getEmojiRegex } from 'emojibase-regex';

async function processEmojis() {
  // Fetch all emoji data, defaulting to English
  const allEmojis = await getEmojiData('en');
  console.log(`Total emojis: ${allEmojis.length}`);

  // Find a specific emoji by hex code (e.g., grinning face)
  const grinningFace = allEmojis.find(emoji => emoji.hexcode === '1F600');
  if (grinningFace) {
    console.log(`Found emoji: ${grinningFace.emoji} - ${grinningFace.label}`);
  }

  // Get a regex that matches all known emojis
  const emojiRegex = getEmojiRegex();
  const text = "Hello world! 👋 This is an example with some emojis: 😂👍🌍.";
  const matchedEmojis = text.match(emojiRegex);

  if (matchedEmojis) {
    console.log(`
Emojis found in text: ${matchedEmojis.join(', ')}`);
  }

  // You can also filter based on properties like 'skins'
  const skinToneEmojis = allEmojis.filter(emoji => emoji.skins && emoji.skins.length > 0);
  console.log(`
Emojis with skin tones: ${skinToneEmojis.slice(0, 5).map(e => e.emoji).join(', ')}...`);
}

processEmojis().catch(console.error);