Filesize Utility

Common errors

• TypeError: filesize is not a function

  cause Incorrect CommonJS `require` or mixed ESM/CJS environment trying to access a default export that no longer exists.
  fix For ESM, use `import { filesize } from 'filesize';`. For CommonJS (since v10), use `const { filesize } = require('filesize');`.

• TypeError: Cannot read properties of undefined (reading 'filesize')

  cause Attempting to destructure a CommonJS `require` statement where the package was imported as a default, or the default export was expected.
  fix Ensure that `filesize` is explicitly imported as a named export. In CommonJS, this means `const { filesize } = require('filesize');`.

• TypeError: filesize called on non-object

  cause Passing an invalid or non-numeric value (e.g., `null`, `undefined`, a string that cannot be parsed) to the `filesize` function.
  fix Ensure the input to `filesize` is a valid `number` or `bigint`.

Warnings

• breaking Since v10.0.0, the CommonJS export is no longer a default export and requires named destructuring, e.g., `const { filesize } = require('filesize');`. Older versions allowed `const filesize = require('filesize');`.
  Fix: Adjust CommonJS `require` statements to use named destructuring: `const { filesize, partial } = require('filesize');`
• breaking Version 10.0.0 dropped support for Node.js 12 and 14. Users on these Node.js versions should remain on `filesize` < v10 or upgrade their Node.js environment.
  Fix: Upgrade Node.js to version 16 or higher, or pin the `filesize` package to a version less than 10.0.0.
• breaking Version 9.0.0 changed the default standard to SI (base 10) from previous defaults, and removed the 'suffix' option. It also dropped support for Node.js 10 and 12.
  Fix: Explicitly set the `standard` option if non-SI behavior is desired (e.g., `{ standard: 'iec', base: 2 }`). If relying on the 'suffix' option, refactor your code as it is no longer available.
• gotcha When using `standard: "iec"`, it is crucial to also set `base: 2` to ensure correct binary (1024-based) calculations and symbols (KiB, MiB). Otherwise, `standard: "iec"` with `base: -1` (auto, often 10) might produce unexpected results or use SI (decimal) calculations with IEC symbols.
  Fix: Always specify `{ standard: 'iec', base: 2 }` together for accurate binary IEC units.

Install

• npm install filesize npm
• yarn add filesize yarn
• pnpm add filesize pnpm

Imports

• filesize
  wrong:

  import filesize from 'filesize';

  correct:

  import { filesize } from 'filesize';

  Since v10.0.0, both ESM and CommonJS imports require named destructuring. The `import filesize from 'filesize'` syntax is incorrect for ESM, and `const filesize = require('filesize');` is incorrect for CJS.
• partial
  wrong:

  const partial = require('filesize');

  correct:

  import { partial } from 'filesize';

  Similar to `filesize`, `partial` is a named export. Ensure named destructuring for both ESM and CommonJS after v10.0.0.
• FileSizeOptions

  import type { FileSizeOptions } from 'filesize';

  Import types separately using `import type` for explicit type annotations in TypeScript environments.

Quickstart

Demonstrates basic filesize conversion, using different standards (SI, IEC), partial application for reusable formatters, and various output formats including string and object.

import { filesize, partial } from 'filesize';

// Convert bytes to a human-readable string using default (SI) standard
const sizeInBytes = 265318;
console.log(`Default SI format: ${filesize(sizeInBytes)}`); // "265.32 kB"

// Use IEC standard with base 2 for binary sizes
const binarySize = 1048576; // 1 MiB
console.log(`IEC binary format: ${filesize(binarySize, { standard: 'iec', base: 2 })}`); // "1 MiB"

// Create a partially applied formatter for consistent styling
const formatBinaryIEC = partial({ standard: 'iec', base: 2, round: 0, spacer: '' });
console.log(`Formatted with partial application: ${formatBinaryIEC(binarySize)}`); // "1MiB"

// Output as an object for programmatic access
const sizeObject = filesize(1536, { output: 'object' });
console.log(`Output as object: ${JSON.stringify(sizeObject)}`); // {"value":1.54,"symbol":"kB","exponent":1,"unit":"kB"}