Vue Timeago Component

Common errors

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

  cause Vue is not globally available or correctly imported before `Vue.use(VueTimeago)` is called. This often happens in module-based setups where Vue is not exposed globally by default, or when using Vue 3's new API.
  fix Ensure `import Vue from 'vue'` is present and Vue is initialized before `Vue.use()`. If using Vue 3, `vue-timeago` is incompatible; use `vue-timeago3` instead.

• Error: Cannot find module 'date-fns/locale/...' or similar module resolution error for date-fns.

  cause The `date-fns` package, or its specific locale files, are not installed or are not correctly resolved by your bundler, especially when using `require()` syntax in an ESM project.
  fix Ensure `date-fns` is installed (`npm install date-fns` or `yarn add date-fns`). Verify your bundler configuration for module resolution, and consider using ESM `import` statements for `date-fns` locales instead of `require()`.

• Invalid Date displayed or incorrect 'time ago' calculation.

  cause The `datetime` prop received by the `<timeago>` component is not a valid Date object, a parsable date string, or a number (timestamp).
  fix Ensure the `datetime` prop is a valid JavaScript `Date` object, a string parseable by `Date.parse()` (e.g., ISO 8601 format), or a Unix timestamp (number of milliseconds since epoch).

Warnings

• breaking Version 5.x introduced `date-fns` as its underlying date utility, which significantly increased bundle size (from ~700 bytes gzipped in v4 to ~2.8kB gzipped in v5). This change also alters the available `converterOptions` as they now map to `date-fns` options.
  Fix: Review bundle size impact and, if critical, consider sticking to older `vue-timeago` versions (e.g., v4) or alternative lightweight solutions if `date-fns`'s features are not fully utilized. Adjust `converterOptions` if migrating from v4.
• gotcha `vue-timeago` is designed for Vue 2 applications. It is not directly compatible with Vue 3 due to changes in Vue's plugin API and component registration. Attempting to use it in a Vue 3 project will result in errors related to `Vue.use()` or component instantiation.
  Fix: For Vue 3 projects, use `vue-timeago3` or `@vueuse/core`'s `useTimeAgo` composable, which are built specifically for Vue 3's composition API or new plugin system.
• gotcha The documentation's locale examples use CommonJS `require('date-fns/locale/...')`. In modern ESM-only or TypeScript projects without specific bundler configurations for CJS, directly using `require` might lead to import errors. Ensure your build setup correctly handles CJS modules or use ESM `import` statements.
  Fix: Replace `require('date-fns/locale/...')` with `import localeName from 'date-fns/locale/locale_name'` and configure your bundler (e.g., Webpack, Vite) to handle `date-fns` imports correctly for ESM environments. Most bundlers will handle `date-fns` CJS builds automatically, but explicit ESM imports are preferred.

Install

• npm install vue-timeago npm
• yarn add vue-timeago yarn
• pnpm add vue-timeago pnpm

Imports

• VueTimeago
  wrong:

  const VueTimeago = require('vue-timeago')

  correct:

  import VueTimeago from 'vue-timeago'

  This is the primary way to import the plugin for global registration with `Vue.use()`.
• Locale (date-fns)
  wrong:

  const zhCN = require('date-fns/locale/zh_cn')

  correct:

  import zhCN from 'date-fns/locale/zh_cn'

  The README examples show CommonJS `require` for date-fns locales. In modern ESM or TypeScript projects, use `import` for tree-shaking and consistency.
• Timeago (component usage)

  <template><timeago :datetime="myDate"></timeago></template>

  After registering the plugin globally, the `<timeago>` component is available in your templates.

Quickstart

This quickstart demonstrates how to install `vue-timeago` as a Vue plugin, register custom `date-fns` locales, and use the `<timeago>` component with various props, including auto-update and custom locales, for both past and future dates.

import Vue from 'vue'
import VueTimeago from 'vue-timeago'
import zhCNLocale from 'date-fns/locale/zh_cn'
import jaLocale from 'date-fns/locale/ja'

// Register the plugin globally
Vue.use(VueTimeago, {
  name: 'Timeago', // Component name
  locale: 'en', // Default locale
  locales: {
    'zh-CN': zhCNLocale,
    ja: jaLocale
  }
})

// Example Vue component usage
export default {
  name: 'App',
  data() {
    return {
      // Use a past date for a clear 'time ago' display
      pastTime: new Date(2023, 10, 15, 10, 30, 0), // November 15, 2023, 10:30:00
      // Use a future date to show 'in X time'
      futureTime: new Date(Date.now() + 1000 * 60 * 60 * 24 * 5) // 5 days from now
    }
  },
  template: `
    <div id="app">
      <h1>Time Ago Examples</h1>
      <p>Simple usage: <timeago :datetime="pastTime"></timeago></p>
      <p>Auto-update every 30 seconds: <timeago :datetime="pastTime" :auto-update="30"></timeago></p>
      <p>Custom locale (Chinese): <timeago :datetime="pastTime" locale="zh-CN"></timeago></p>
      <p>Future date: <timeago :datetime="futureTime"></timeago></p>
    </div>
  `
}