Word Wrapping for JavaScript

Common errors

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use `require()` in an ECMAScript Module (ESM) file (e.g., a file ending in `.js` when `type: "module"` is set in `package.json`, or a `.mjs` file).
  fix Use the ESM `import` syntax: `import wordwrap from 'wordwrapjs'`. Ensure your environment (Node.js, bundler) is configured for ESM.

• Error [ERR_REQUIRE_ESM]: require() of ES Module ... wordwrapjs/dist/index.mjs from ... not supported.

  cause A CommonJS module is trying to `require()` the ESM build of `wordwrapjs`. This happens when a CJS project tries to import an ESM-only package or when module resolution incorrectly picks the ESM entry point.
  fix Ensure your `package.json` for the consuming project does not have `"type": "module"` if you intend to use CommonJS. If you are using CJS, ensure `wordwrapjs`'s CJS entry point is correctly resolved, or consider migrating your project to ESM.

• Text wraps unexpectedly, leaving long words on their own line exceeding width.

  cause The default behavior of `wordwrapjs` is not to break individual words, even if they are longer than the specified `width`. The entire word is moved to the next line.
  fix To force long words to break at the specified width, pass the `break: true` option: `wordwrap.wrap(text, { width: 20, break: true })`.

• Trailing whitespace appears on wrapped lines.

  cause By default, `wordwrapjs` trims whitespace from the end of each line. If `noTrim` option is set to `true`, trailing whitespace will be preserved.
  fix Ensure the `noTrim` option is not explicitly set to `true` if you want lines to be trimmed. The default behavior should trim lines automatically. If you desire specific trimming, manage it manually after wrapping.

Warnings

• gotcha When wrapping text for terminal output, ANSI escape codes (e.g., for colors) are counted as characters towards the `width` option, leading to incorrect visual wrapping. This library is designed for plain text.
  Fix: Manually strip ANSI escape codes before passing text to `wordwrapjs`, or use a library specifically designed for wrapping text with ANSI support.
• gotcha By default, words longer than the specified `width` will not be broken; instead, the entire word will be placed on its own line, potentially exceeding the `width`. To force long words to break, the `break: true` option must be explicitly set.
  Fix: Pass `{ break: true }` in the options object to `wrap` or `lines` methods: `wordwrap.wrap(text, { width: 20, break: true })`.
• gotcha Interoperability between CommonJS (CJS) and ECMAScript Modules (ESM) in Node.js can be complex. While `wordwrapjs` provides both CJS (`require`) and ESM (`import`) entry points, mixing them in a single project can lead to `ERR_REQUIRE_ESM` or unexpected behavior in older Node.js versions or complex build setups.
  Fix: Ensure your project consistently uses either CJS or ESM. If you must mix them, verify your Node.js version supports the interoperability patterns you're using (Node.js >=12.17 for `wordwrapjs`), and be aware of synchronous vs. asynchronous loading differences. Consider explicit file extensions (`.mjs`, `.cjs`) or `type: "module"` in `package.json`.

Install

• npm install wordwrapjs npm
• yarn add wordwrapjs yarn
• pnpm add wordwrapjs pnpm

Imports

• wordwrap
  wrong:

  import { wordwrap } from 'wordwrapjs'

  correct:

  import wordwrap from 'wordwrapjs'

  The primary API is accessed via the default export, which provides static methods like `wrap` and `lines`.
• wordwrap
  wrong:

  const { wordwrap } = require('wordwrapjs')

  correct:

  const wordwrap = require('wordwrapjs')

  For CommonJS environments, the entire module export is typically assigned to a variable to access static methods.
• WordwrapOptions

  import type { WordwrapOptions } from 'wordwrapjs'

  Import the type definition for options object if using TypeScript.

Quickstart

Demonstrates basic word wrapping with `wrap` and `lines` methods, including options for breaking long words and handling URLs. It shows the difference between breaking and not breaking long words for a given width.

import wordwrap from 'wordwrapjs'

const longText = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.'

// Wrap text to a 30-character width, allowing long words to break
const wrappedText = wordwrap.wrap(longText, { width: 30, break: true })
console.log('--- Wrapped Text (width 30, break: true) ---\n' + wrappedText)

const url = 'https://this-is-a-very-long-url-that-exceeds-the-column-width.com/path/to/resource'

// Wrap a long URL into lines, forcing breaks
const urlLines = wordwrap.lines(url, { width: 25, break: true })
console.log('\n--- Wrapped URL (width 25, break: true) ---')
urlLines.forEach(line => console.log(line))

// Wrap without forcing breaks (default behavior for long words)
const noBreakLines = wordwrap.lines(url, { width: 25 })
console.log('\n--- Wrapped URL (width 25, no break) ---')
noBreakLines.forEach(line => console.log(line))