anywhen

library0.3.1jsnpmunverified

anywhen is a tiny (1.1kb gzip) zero-dependency date formatter that provides three modes: smart (context-aware, showing relative or absolute depending on distance from now), absolute (via Intl.DateTimeFormat), and relative (via Intl.RelativeTimeFormat). It supports any Intl locale out of the box, requires no locale files or plugins, and ships TypeScript types. Current stable version is 0.3.1. It is actively maintained (as of mid-2025) and is more lightweight than libraries like dayjs or date-fns while focusing specifically on human-readable output. Key differentiators: single function with intelligent defaults, SSR-safe with custom `now` and `timeZone` options, and no dependencies.

productivity

npm install anywhen

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ANYWHEN

anywhen

productivityjavascriptv0.3.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

anywhen

✓ import { anywhen } from 'anywhen'

✗ import anywhen from 'anywhen'

anywhen is a named export, not a default export. Using default import will result in undefined at runtime.

AnywhenOptions

✓ import type { AnywhenOptions } from 'anywhen'

✗ import { AnywhenOptions } from 'anywhen'

TypeScript type import; erase at runtime. Using a value import may cause bundler warnings.

AnywhenMode

✓ import type { AnywhenMode } from 'anywhen'

Only needed when explicitly referencing mode types; TypeScript will infer them otherwise.

Demonstrates smart, absolute, and relative modes with various locales and SSR-safe options.

import { anywhen } from 'anywhen'; const now = new Date(); const past = new Date(Date.now() - 1000 * 60 * 60 * 3); // 3 hours ago const future = new Date(Date.now() + 1000 * 60 * 60 * 24 * 7); // 1 week // Smart mode (default) console.log(anywhen(now)); // "now" console.log(anywhen(past)); // "3 hours ago" console.log(anywhen(future)); // "in 7 days" // Absolute mode with locale & custom format console.log(anywhen(now, { mode: 'absolute', locale: 'de', format: { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' } })); // Relative mode console.log(anywhen(past, { mode: 'relative', locale: 'fr' })); // "il y a 3 heures" // SSR-safe with explicit now and timezone const requestTime = new Date(); console.log(anywhen(now, { locale: 'en', now: requestTime, timeZone: 'America/New_York' }));

Debug

Known issues

gotchaDefault import `import anywhen from 'anywhen'` returns undefined

fix

Use named import: `import { anywhen } from 'anywhen'`

affects: >=0.1.0

gotcha`input` must be a Date, number (unix timestamp ms), or ISO 8601 string; string that is not ISO 8601 will cause Invalid Date

fix

Ensure input is valid: new Date(), Date.now(), or '2025-06-15T10:00:00.000Z'

affects: >=0.1.0

gotchaRelative mode uses Intl.RelativeTimeFormat; some older browsers (e.g., Safari <14) do not support it, causing fallback to absolute in smart mode or error in relative mode

fix

Polyfill Intl.RelativeTimeFormat or use a fallback library for older browsers

affects: >=0.1.0

gotchaSmart mode with `time: true` shows clock for yesterday/today; may not be desired in compact UIs

fix

Set `time: false` to hide clock: `anywhen(date, { time: false })`

affects: >=0.1.0

gotchaPassing `locale` that is not supported by the environment falls back to the runtime default (e.g., en-US), not the system locale

fix

Verify Intl support for the desired locale; or use a locale polyfill

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: anywhen is not a function

Using default import instead of named import

fix

Replace `import anywhen from 'anywhen'` with `import { anywhen } from 'anywhen'`

Invalid time value

Passed an unsupported string format (e.g., '2025/06/15') or non-Date/number/ISO string

fix

Ensure input is a Date, number (milliseconds), or ISO 8601 string. Use `new Date('2025-06-15T10:00:00Z')` instead of non-standard formats.

RangeError: Invalid time zone specified

Passed an invalid timeZone identifier (e.g., 'America/Invalid')

fix

Use a valid IANA time zone name like 'America/New_York' or 'Europe/London'. Check Intl.supportedValuesOf('timeZone').

Upgrade

Version history

0.3.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

60 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/kirilinsky/anywhen ↗

packageanywhen ↗

homepagehttps://github.com/kirilinsky/anywhen#readme ↗