Maintained compatibility package

@stackline/wcwidth

Measure terminal columns with a callable historical API, reproducible Unicode 17.0.0 tables, and grapheme-aware emoji widths.

Browse source

Start here

One callable width function

npm install @stackline/wcwidth@1.0.0

CommonJS

'use strict'

const wcwidth = require('@stackline/wcwidth')

console.log(wcwidth('A字🤦🏼‍♂️e\u0301'))
console.log(wcwidth.config({ control: -1 })('line one\nline two'))

ES modules

import wcwidth, { unicodeVersion } from '@stackline/wcwidth'

console.log(wcwidth('🇨🇦'))
console.log(unicodeVersion)

Compatibility

Keep the API; make Unicode current

Callable CommonJS

The package root remains a function named wcwidth with one argument and no nested default property.

Compatible configuration

config({ nul, control }) preserves the historical defaults, object fill, inheritance, retained mutation, and control-width behavior.

Native ESM and types

A native ESM default plus named config and unicodeVersion exports have conditional TypeScript declarations.

Root-only closure

The production install contains one package node with zero runtime, optional, peer, or bundled dependencies.

The runnable CommonJS example above includes strict control-character configuration.

Deterministic data

Unicode 17 by grapheme cluster

Maintained terminal-width rules
Input category	Columns
Combining and zero-width characters	0
East Asian Wide and Fullwidth characters	2
East Asian Ambiguous characters	1
Flags, keycaps, emoji presentation and qualifying emoji ZWJ clusters	2 per grapheme cluster
Ordinary scalar values	1

Generated tables come from checksum-pinned Unicode 17.0.0 sources. Results do not depend on the host Node.js ICU version.

Adoption

Keep the historical import key

An npm alias lets existing require('wcwidth') imports remain unchanged.

{
  "dependencies": {
    "wcwidth": "npm:@stackline/wcwidth@1.0.0"
  }
}

Run a clean install and the downstream test, type, build, and snapshot suites. Review output containing emoji, combining text, CJK, or characters added after the historical Unicode tables.

Release evidence

What the package gate covers

Historical API characterization and reviewed full-BMP differential results.
Unicode grapheme and fully-qualified emoji conformance corpora, table invariants, and bounded stress cases.
CommonJS, ESM, browser bundling, npm alias, and TypeScript 3.9/current consumers.
Strict package/type lint, licenses, one-node closure, CycloneDX SBOM, audits, artifact identity, signatures, and provenance.

Verification guide · Full compatibility contract · Migration guide · Security policy

Independent maintenance and attribution

This package is independently maintained and is not affiliated with or endorsed by Tim Oxley, Jun Woong, Markus Kuhn, the original project, or the Unicode Consortium. Original and Unicode attribution is preserved.