pretty-bytes

pretty-bytes is a zero-dependency utility that turns raw byte counts into strings people can actually read, converting 1337 into 1.34 kB using SI decimal units by default. It handles both number and bigint inputs, so it works equally well for small UI values and for arbitrarily large byte counts that would otherwise lose precision in a Number.

Beyond the basic conversion, it exposes a focused set of options for real-world display needs: binary (KiB/MiB) units for memory reporting, bit units for bitrate displays, signed output for diffs, locale-aware number formatting, explicit fraction-digit control, and fixed-width padding for aligning values in tables or progress bars. The whole implementation ships as a single small ESM module with a hand-written TypeScript declaration file, making it a common building block wherever a byte count needs to be shown to a user.

What You Get

• A single prettyBytes(number, options?) function with no runtime dependencies, distributed as ESM with bundled TypeScript types.
• Support for both number and bigint inputs, so extremely large byte counts (beyond safe integer range) still format correctly.
• SI (kB, MB, GB…) and binary (KiB, MiB, GiB…) unit modes, plus a parallel bit/bibit mode for bitrate displays.
• Locale-aware output via Intl-backed toLocaleString, with explicit minimum/maximum fraction-digit control and truncation instead of rounding when digits are specified.
• A fixedWidth option that right-pads results for aligned columns in tables, logs, or progress bars.

Common Use Cases

• Displaying file sizes in upload/download UIs, file managers, or admin dashboards.
• Formatting memory, disk, or bandwidth usage in CLI tools and monitoring dashboards.
• Showing bitrate or transfer-speed figures in networking or media tooling.
• Rendering aligned, fixed-width byte columns in terminal tables or progress bars.

Under The Hood

Architecture The whole package is a single ESM module (index.js) built from small, composable pure functions rather than a class or stateful pipeline: toLocaleString handles locale-aware number rendering, log10/log/divide implement bigint-safe math (since Math.log/division don’t work directly on bigint), buildLocaleOptions translates the public options into Intl number-format options, and applyFixedWidth handles the final padding step. The exported prettyBytes function composes these in a clear linear flow — validate input, normalize options, pick a unit table, compute the exponent, divide, format, then pad — so despite having no internal module boundaries, the separation of concerns is explicit and each helper could be swapped or extended (e.g. new unit tables) without touching the others.

Tech Stack The package has zero runtime dependencies and ships as pure ESM ("type": "module") targeting Node.js 20+, relying only on built-in Number#toLocaleString/Intl for localization. Its devDependencies are entirely tooling: ava for the test runner, xo (an opinionated ESLint preset used across Sindre Sorhus’s packages) for linting, and tsd for type-level testing against the hand-written index.d.ts. There is no build step — the published package is the same JavaScript and declaration file present in the repo.

Code Quality The test suite (test.js) is extensive relative to the package’s size, covering invalid-input errors, bigint vs number parity, rounding behavior at every unit boundary, binary vs SI units, locale formatting, signed output, and fixed-width padding edge cases. Type safety is enforced two ways: a hand-authored index.d.ts with JSDoc-documented options, and index.test-d.ts running tsd type-level assertions against it. Error handling is explicit — invalid numeric input and invalid fixedWidth values throw descriptive TypeErrors rather than failing silently. GitHub Actions CI (.github/workflows) runs the xo && ava && tsd script on each change.

API Design The public surface is a single function with sensible defaults (unlabeled call prettyBytes(1337) just works), and every non-default behavior is opt-in through a flat options object — signed, bits, binary, locale, minimumFractionDigits, maximumFractionDigits, space, nonBreakingSpace, fixedWidth. This keeps the common case a one-line call while still covering less common needs like bitrate display, table alignment, and internationalization without requiring a second API or configuration object. Documentation in the README and type declarations pairs every option with a runnable example, which keeps the learning curve low despite the fairly broad option surface.