Package Exports

native-time-ago
native-time-ago/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (native-time-ago) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

native-time-ago

A tiny, zero-dependency utility that converts JavaScript Dates into human-readable strings like "3 hours ago" or "in 2 days" using native browser APIs.

Why? • Install • Usage • Locales

Why?

The native Intl.RelativeTimeFormat API is powerful, but it's "dumb"—it doesn't calculate time differences. If you want "3 hours ago," you have to manually calculate how many seconds have passed, divide by 3600 to get hours, and then pass exactly (-3, "hours") to the native formatter.

This package handles the math. It takes a date, calculates the optimal unit (seconds → minutes → hours → days → weeks → months → years), and passes the correct number and unit to the native formatter.

Features

Zero Dependencies - Only ~1388 bytes
100+ Languages - Supports any locale via Intl.RelativeTimeFormat
Framework Agnostic - Works in React, Vue, Svelte, Angular, Node.js, Bun
Auto-updating - Translations improve as browsers update

Install

npm install native-time-ago

Usage

import timeAgo from 'native-time-ago';

// Basic usage
timeAgo(new Date(Date.now() - 3 * 60 * 60 * 1000));  // "3 hours ago"
timeAgo(new Date('2026-03-03T12:00:00Z'));            // "3 hours ago"

// Future dates
timeAgo(new Date(Date.now() + 2 * 24 * 60 * 60 * 1000));  // "in 2 days"

// Different locales
timeAgo(new Date(Date.now() - 3 * 60 * 60 * 1000), 'es');  // "hace 3 horas"
timeAgo(new Date(Date.now() - 3 * 60 * 60 * 1000), 'ja');  // "3 時間前"
timeAgo(new Date(Date.now() - 3 * 60 * 60 * 1000), 'fr');  // "il y a 3 heures"

// Pass string or number
timeAgo('2026-03-03T12:00:00Z', 'en');
timeAgo(1709476800000, 'en');

Comparison

// OLD WAY (heavy, many dependencies)
import { formatDistanceToNow } from 'date-fns';
import { es } from 'date-fns/locale';
formatDistanceToNow(new Date(2026, 2, 3), { locale: es, addSuffix: true });

// NEW WAY (zero dependencies)
import timeAgo from 'native-time-ago';
timeAgo(new Date('2026-03-03T12:00:00Z'), 'es');

Supported Locales

Any locale supported by Intl.RelativeTimeFormat:

en, es, fr, de, it, pt, ru, ja, ko, zh, ar, and 100+ more

API

timeAgo(date, locale?)

date - Date | string | number - The date to format
locale - string - Optional locale code (default: 'en')

Returns a string like "3 hours ago", "in 2 days", or "now".

License

MIT