Text Hyphenation Library

Common errors

• TypeError: hyphenate is not a function

  cause Attempting to import `hyphenate` from the root `hyphen` package instead of a language-specific module, or trying to use a `require` statement in an ESM-only context.
  fix Change the import path to a language-specific module, e.g., `import { hyphenate } from 'hyphen/en';`. If using CommonJS, ensure your environment supports dynamic `import()` or switch to an ESM-aware setup.

• Module not found: Can't resolve 'hyphen/en'

  cause The package `hyphen` or its language-specific modules are not correctly installed or the build environment does not resolve ESM paths correctly.
  fix Run `npm install hyphen` or `yarn add hyphen`. Ensure your bundler (Webpack, Rollup, etc.) is configured to handle ES Modules and module resolution correctly. Check for typos in the import path.

• Words are not hyphenated as expected, or too many words are hyphenated.

  cause Misconfiguration of `exceptions`, `minWordLength`, or an incorrect language module being used.
  fix Verify the `exceptions` array contains the correct words to exclude. Adjust `minWordLength` to control the shortest words hyphenated. Ensure the correct language module (e.g., `hyphen/de` for German) is imported for the given text.

Warnings

• gotcha The library exports distinct asynchronous (`hyphenate`) and synchronous (`hyphenateSync`) functions. Mixing them up or attempting to `await` the synchronous version will not work as expected.
  Fix: Always import and use the correct function for your desired behavior: `import { hyphenate } from 'hyphen/en'` for async, and `import { hyphenateSync } from 'hyphen/en'` for sync.
• gotcha Hyphenation patterns are loaded per language via specific import paths (e.g., `hyphen/en`, `hyphen/de`). Importing directly from `hyphen` (e.g., `import { hyphenate } from 'hyphen'`) will not provide the hyphenation function and will likely result in an undefined or module not found error.
  Fix: Ensure you import from the correct language-specific module, e.g., `import { hyphenate } from 'hyphen/en';`.
• gotcha The default hyphenation character (`hyphenChar`) is `\u00AD` (soft hyphen), which is often invisible but indicates a potential line break. If you need a visible hyphen or a different character, you must explicitly configure it.
  Fix: Pass an `options` object with `hyphenChar` set to your desired character, e.g., `{ hyphenChar: '-' }` or `{ hyphenChar: '·' }`.
• gotcha When hyphenating HTML, the library attempts to skip HTML tags. However, malformed HTML or extremely complex structures might not be parsed correctly, potentially leading to hyphenation within tag attributes or unexpected places.
  Fix: Ensure HTML input is well-formed. For very complex or untrusted HTML, consider pre-processing the text to extract plain text segments, hyphenate them, and then re-insert into the HTML structure, or use a dedicated HTML parsing library in conjunction.

Install

• npm install hyphen npm
• yarn add hyphen yarn
• pnpm add hyphen pnpm

Imports

• hyphenate
  wrong:

  const { hyphenate } = require('hyphen/en');

  correct:

  import { hyphenate } from 'hyphen/en';

  Hyphenation functions are imported from language-specific paths (e.g., 'hyphen/en', 'hyphen/de'). CommonJS `require` is not directly supported; use dynamic import or an ESM-aware bundler.
• hyphenateSync
  wrong:

  import { hyphenate } from 'hyphen/de'; // for sync

  correct:

  import { hyphenateSync } from 'hyphen/de';

  Use `hyphenateSync` for synchronous operations. The default `hyphenate` function is asynchronous.
• * as hyphenEn
  wrong:

  import hyphenEn from 'hyphen/en';

  correct:

  import * as hyphenEn from 'hyphen/en';

  Language modules export named functions (`hyphenate`, `hyphenateSync`), not a default export. Use `* as` for grouping or named imports directly.

Quickstart

Demonstrates asynchronous and synchronous hyphenation for English and German text, including custom options like exceptions and hyphenation character.

import { hyphenate } from "hyphen/en";

(async () => {
  const text = "A certain king had a beautiful garden that needed careful tending and regular watering.";

  // Example with custom options
  const options = {
    exceptions: ["beautiful"], // Don't hyphenate 'beautiful'
    hyphenChar: '·', // Use a middle dot instead of soft hyphen
    minWordLength: 6 // Only hyphenate words 6 characters or longer
  };

  const result = await hyphenate(text, options);
  console.log(result);
  // Expected output (approx): "A cer·tain king had a beautiful gar·den that need·ed care·ful tend·ing and reg·u·lar wa·ter·ing."

  // Using the synchronous version for a different language
  const { hyphenateSync } = await import('hyphen/de');
  const germanText = "Ein gewisser König hatte einen wunderschönen Garten, der sorgfältige Pflege und regelmäßiges Gießen benötigte.";
  const germanResult = hyphenateSync(germanText);
  console.log(germanResult);
  // Expected output (approx): "Ein ge·wis·ser Kö·nig hat·te einen wun·der·schö·nen Gar·ten, der sorg·fäl·ti·ge Pfle·ge und re·gel·mä·ßi·ges Gie·ßen be·nö·tig·te."
})();