{"id":11400,"library":"nlcst-emoji-modifier","title":"NLCST Emoji Modifier","description":"The `nlcst-emoji-modifier` package is an NLCST utility designed to classify both standard Unicode emoji (e.g., 👍) and GitHub-style gemoji shortcodes (e.g., `:cat:`) within natural language text by transforming them into `EmoticonNode`s in the syntax tree. The current stable version is 6.0.2. This project, part of the `unified` collective, releases new major versions aligned with Node.js LTS support, dependency updates, and shifts to modern JavaScript module practices, ensuring ongoing compatibility and performance. It functions as a foundational component for advanced linguistic analysis, often used implicitly by higher-level plugins like `retext-emoji`. Its key differentiator lies in its specific integration within the NLCST ecosystem for detailed emoji and emoticon processing.","status":"active","version":"6.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/nlcst-emoji-modifier","tags":["javascript","unist","nlcst","nlcst-util","util","utility","emoticon","emoji","typescript"],"install":[{"cmd":"npm install nlcst-emoji-modifier","lang":"bash","label":"npm"},{"cmd":"yarn add nlcst-emoji-modifier","lang":"bash","label":"yarn"},{"cmd":"pnpm add nlcst-emoji-modifier","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides TypeScript type definitions for NLCST nodes.","package":"@types/nlcst","optional":false},{"reason":"Required for importing the `Emoticon` type definition for TypeScript users after v6.0.0, although not a direct runtime dependency for the `emojiModifier` function itself.","package":"nlcst-emoticon-modifier","optional":true}],"imports":[{"note":"The package is ESM-only since v5.0.0, and Node.js 16+ is required since v6.0.0. CommonJS `require` will result in errors.","wrong":"const emojiModifier = require('nlcst-emoji-modifier')","symbol":"emojiModifier","correct":"import { emojiModifier } from 'nlcst-emoji-modifier'"},{"note":"Since v6.0.0, the `Emoticon` type has been moved to the `nlcst-emoticon-modifier` package. Attempting to import it from `nlcst-emoji-modifier` will fail.","wrong":"import type { Emoticon } from 'nlcst-emoji-modifier'","symbol":"Emoticon","correct":"import type { Emoticon } from 'nlcst-emoticon-modifier'"},{"note":"For Deno and browser environments, use `esm.sh` with the major version specifier for direct module imports.","symbol":"emojiModifier (Deno/Browser)","correct":"import {emojiModifier} from 'https://esm.sh/nlcst-emoji-modifier@6'"}],"quickstart":{"code":"import {emojiModifier} from 'nlcst-emoji-modifier'\nimport {ParseEnglish} from 'parse-english'\nimport {inspect} from 'unist-util-inspect'\n\nconst english = new ParseEnglish()\nenglish.tokenizeSentencePlugins.unshift(emojiModifier)\n\nconsole.log(inspect(english.parse('It’s raining :cat:s and :dog:s.')))\n\n// Expected output (simplified):\n// RootNode\n// └─ ParagraphNode\n//    └─ SentenceNode\n//       ├─ WordNode: \"It’s\"\n//       ├─ WhiteSpaceNode: \" \"\n//       ├─ WordNode: \"raining\"\n//       ├─ WhiteSpaceNode: \" \"\n//       ├─ EmoticonNode: \":cat:\"\n//       ├─ WordNode: \"s\"\n//       ├─ WhiteSpaceNode: \" \"\n//       ├─ WordNode: \"and\"\n//       ├─ WhiteSpaceNode: \" \"\n//       ├─ EmoticonNode: \":dog:\"\n//       └─ WordNode: \"s.\"","lang":"javascript","description":"This example demonstrates how to integrate `nlcst-emoji-modifier` into a `ParseEnglish` pipeline to tokenize emoji and gemoji shortcodes as `EmoticonNode`s."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or newer. For projects requiring older Node.js, pin `nlcst-emoji-modifier` to `<6.0.0`.","message":"Version 6.0.0 requires Node.js 16 or higher. Older Node.js versions are no longer supported.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json` or `.mjs` files) and use `import { emojiModifier } from 'nlcst-emoji-modifier'` instead of `require()`.","message":"The package transitioned to ESM-only starting from v5.0.0, and explicitly uses the `exports` field since v6.0.0. This significantly changes how it's imported.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Update your type imports to `import type { Emoticon } from 'nlcst-emoticon-modifier'`. You may need to install `nlcst-emoticon-modifier` if you haven't already.","message":"The `Emoticon` TypeScript type was removed from `nlcst-emoji-modifier` in v6.0.0. It is now exported by `nlcst-emoticon-modifier`.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Modify your code to expect `undefined` from `emojiModifier` and adjust subsequent logic accordingly. The modifier operates by side-effect on the passed `node`.","message":"The `emojiModifier` function now explicitly yields `undefined` (returns nothing). If you were relying on a return value, your code will need adjustment.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Review your TypeScript configurations and usages of `unist-util-visit` within your dependency tree, ensuring compatibility with its v2.0.0 API.","message":"Version 4.0.0 updated `unist-util-visit`, which could be a breaking change for TypeScript users who didn't explicitly expect TypeScript in their dependents.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Evaluate if `retext-emoji` better suits your needs for general emoji processing in `retext` pipelines, as it wraps `nlcst-emoji-modifier`.","message":"This utility is a low-level NLCST modifier. For a higher-level, easier-to-use abstraction that integrates this and other related utilities, consider `retext-emoji`.","severity":"gotcha","affected_versions":"always"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Convert your file to an ES module (e.g., by adding `\"type\": \"module\"` to `package.json` or renaming to `.mjs`) and use `import { emojiModifier } from 'nlcst-emoji-modifier'`.","cause":"Attempting to use CommonJS `require()` syntax to import `nlcst-emoji-modifier` which is an ESM-only package.","error":"TypeError: emojiModifier is not a function"},{"fix":"Ensure your Node.js environment or build setup treats your files as ES modules. This might involve setting `\"type\": \"module\"` in your `package.json` or explicitly using `.mjs` file extensions.","cause":"Using ES module `import` syntax in a CommonJS context without proper configuration.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"You must use `import()` or convert your consuming module to ESM. For example, `import { emojiModifier } from 'nlcst-emoji-modifier'`.","cause":"Trying to `require()` this package (ESM-only) from a CommonJS module.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module [path] not supported. Instead change the require of [path] to a dynamic import() or change 'type': 'module' in your package.json or use a .mjs extension."},{"fix":"The `Emoticon` type was moved. Import it from `nlcst-emoticon-modifier` instead: `import type { Emoticon } from 'nlcst-emoticon-modifier'`.","cause":"TypeScript error when trying to import the `Emoticon` type from `nlcst-emoji-modifier` after version 6.0.0.","error":"Property 'Emoticon' does not exist on type 'typeof import(\"nlcst-emoji-modifier\")'"},{"fix":"Upgrade your Node.js runtime to version 16 or newer. Verify your `package.json` `engines` field if distributing your package.","cause":"Running `nlcst-emoji-modifier` v6.0.0+ on an unsupported Node.js version (<16).","error":"UnhandledPromiseRejectionWarning: Error: [Error message about Node.js version]"}],"ecosystem":"npm"}