timeago.js

timeago.js is a tiny (under 2kb gzipped) library that converts a timestamp or Date into a human-readable relative-time string, like “3 hours ago” or “in 24 days”. It supports both past (ago) and future (in) statements, ships built-in translations for 50+ languages, and can render live-updating timestamps in the DOM that automatically refresh as time passes.

The core API is three functions — format() for a one-off string, render() to bind and auto-update DOM elements, and register() to add a custom locale — plus cancel() to stop a real-time render. It works identically in Node.js and the browser (including a UMD build for direct <script> tag usage), and companion packages provide React (timeago-react) and Python (timeago) ports of the same formatting logic.

What You Get

• format(date, locale) for converting a Date/timestamp into a relative-time string in any of 50+ built-in locales
• render(nodes, locale) to bind DOM elements to a live-updating relative timestamp that refreshes automatically
• register(locale, localeFunc) for adding custom or missing language translations
• cancel(node) to stop a real-time render on a specific element
• A full.ts variant producing a full/verbose time-ago phrase alongside the standard short form

Common Use Cases

• Displaying “posted 3 hours ago” style timestamps on comments, social feeds, or activity logs
• Live-updating relative timestamps in a dashboard or chat UI without re-rendering the whole component tree
• Internationalized apps needing relative-time strings in a specific locale out of the box
• Lightweight projects avoiding a heavier date library (Moment.js, date-fns) just for time-ago formatting

Under The Hood

Architecture - src/format.ts holds the core diff-and-bucket logic that maps a time delta to a unit and phrase, src/lang/ contains one file per locale (56 total) each exporting a phrase-lookup function, src/render.ts/realtime.ts wrap format() with a setInterval loop that walks bound DOM nodes and updates their text content, and src/register.ts lets callers add a custom locale to the same lookup table used internally. Tech Stack - Written in TypeScript, built with Vite (three separate configs: standard, full, and UMD builds) to produce ESM/CJS/UMD outputs plus a minified browser bundle, tested with Vitest and coverage reporting via Coveralls. Code Quality - __tests__/ mirrors the source 1:1 (format.spec.ts, render.spec.ts equivalents, full.spec.ts, register.spec.ts) plus a dedicated lang test directory verifying every locale’s output, giving strong confidence that the 56 shipped translations are each correct. API Design - The four-function surface (format, render, cancel, register) is deliberately minimal, and both Node/import and <script>-tag/UMD usage are supported identically, keeping the barrier to first use to a single import statement.