1. Pourquoi Day.js ?

Day.js est une bibliothèque légère de manipulation de dates — seulement 2 KB minifiée et gzippée. Elle offre une API presque identique à Moment.js mais sans les 300 KB de baggage.

Le problème avec les dates natives

L'objet Date de JavaScript natif est réputé pour ses comportements incohérents : mois indexés à 0, parsing ambigu, absence d'immutabilité, formatage limité. Day.js résout tous ces problèmes avec une API intuitive et prévisible.

// Problème natif — month 0 = janvier, 11 = décembre
const d = new Date(2024, 0, 15); // 15 janvier 2024 ✓ mais peu lisible

// Avec Day.js — clair et intuitif
const d = dayjs('2024-01-15'); // 15 janvier 2024 ✓

Day.js vs Moment.js vs date-fns

Immutabilité — une propriété clé

Chaque opération Day.js retourne un nouvel objet, sans modifier l'original.

const base = dayjs('2024-06-15');
const demain = base.add(1, 'day');
const hierr  = base.subtract(1, 'day');

console.log(base.format());   // 2024-06-15 — inchangé !
console.log(demain.format()); // 2024-06-16
console.log(hierr.format());  // 2024-06-14

2. Parsing & création

Day.js accepte de nombreux formats d'entrée pour créer des objets de date. La fonction dayjs() est le point d'entrée principal.

Méthodes de création

// Date actuelle
const maintenant = dayjs();

// Depuis une chaîne ISO 8601
const iso = dayjs('2024-01-15');
const iso2 = dayjs('2024-01-15T14:30:00');

// Depuis un timestamp Unix (secondes)
const unix = dayjs.unix(1705276200);

// Depuis un objet Date natif
const native = dayjs(new Date(2024, 0, 15));

// Depuis un timestamp ms
const ms = dayjs(1705276200000);

// Depuis un objet littéral
const obj = dayjs({ year: 2024, month: 0, day: 15 }); // month: 0 = janvier

Validation avec .isValid()

dayjs('2024-01-15').isValid();    // true
dayjs('pas-une-date').isValid();   // false
dayjs('2024-13-01').isValid();     // false (mois 13)
dayjs(null).isValid();             // false
dayjs(undefined).isValid();        // true (= maintenant)
dayjs('').isValid();               // false

Accéder aux composantes

const d = dayjs('2024-06-15T14:30:45');

d.year();        // 2024
d.month();       // 5  ← attention : 0-indexé (0 = janv, 5 = juin)
d.date();        // 15 (jour du mois)
d.day();         // 6  (jour de la semaine, 0 = dimanche)
d.hour();        // 14
d.minute();      // 30
d.second();      // 45
d.millisecond(); // 0
d.valueOf();     // timestamp ms (1718455845000)

3. Formatage

La méthode .format() convertit un objet Day.js en chaîne selon un patron de tokens. Avec la locale française, les noms de jours et de mois sont traduits automatiquement.

Exemples de formatage

const d = dayjs('2024-06-15T14:30:00');

d.format('DD/MM/YYYY');           // "15/06/2024"
d.format('DD/MM/YYYY HH:mm');     // "15/06/2024 14:30"
d.format('YYYY-MM-DD');           // "2024-06-15"  (ISO)
d.format('DD MMMM YYYY');         // "15 juin 2024"  (avec locale fr)
d.format('dddd D MMMM YYYY');     // "samedi 15 juin 2024"
d.format('HH:mm:ss');             // "14:30:00"
d.format('[Le] DD/MM [à] HH[h]mm'); // "Le 15/06 à 14h30"  (texte entre [])

Table des tokens

Activer la locale française

<!-- Charger Day.js + locale fr + plugin relativeTime -->
<script src="https://cdn.jsdelivr.net/npm/dayjs@1/dayjs.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dayjs@1/locale/fr.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dayjs@1/plugin/relativeTime.js"></script>
<script>
  dayjs.locale('fr');
  dayjs.extend(window.dayjs_plugin_relativeTime);

  // Maintenant :
  dayjs('2024-06-15').format('dddd D MMMM YYYY');
  // → "samedi 15 juin 2024"
</script>

.toISOString() et .toString()

const d = dayjs('2024-06-15');

d.toISOString();  // "2024-06-15T00:00:00.000Z"
d.toString();     // "Sat Jun 15 2024 00:00:00 GMT+0000"
d.toDate();       // objet Date natif
d.valueOf();      // 1718409600000 (timestamp ms)

4. Manipulation

Day.js offre des méthodes de manipulation fluides et chaînables. Toutes retournent un nouvel objet Day.js (immutabilité).

.add() et .subtract()

const aujourd = dayjs('2024-06-15');

// Ajouter
aujourd.add(7, 'day');      // 22 juin 2024
aujourd.add(2, 'month');    // 15 août 2024
aujourd.add(1, 'year');     // 15 juin 2025
aujourd.add(3, 'hour');     // 15 juin 2024 03:00

// Soustraire
aujourd.subtract(1, 'week');   // 8 juin 2024
aujourd.subtract(6, 'month');  // 15 décembre 2023

// Unités disponibles
// year(s), month(s), week(s), day(s), hour(s), minute(s), second(s), millisecond(s)

.startOf() et .endOf()

const d = dayjs('2024-06-15T14:30:45');

d.startOf('year');   // 2024-01-01 00:00:00
d.startOf('month');  // 2024-06-01 00:00:00
d.startOf('week');   // 2024-06-09 00:00:00  (dimanche, semaine anglaise)
d.startOf('day');    // 2024-06-15 00:00:00
d.startOf('hour');   // 2024-06-15 14:00:00

d.endOf('month');    // 2024-06-30 23:59:59
d.endOf('year');     // 2024-12-31 23:59:59
d.endOf('day');      // 2024-06-15 23:59:59

.set() pour modifier un composant

const d = dayjs('2024-06-15');

d.set('year', 2025);    // 2025-06-15
d.set('month', 11);     // 2024-12-15  (0-indexé : 11 = déc)
d.set('date', 1);       // 2024-06-01
d.set('hour', 9);       // 2024-06-15 09:00:00

// Chaîner les modifications
d.set('year', 2025).set('month', 0).set('date', 1);
// → 2025-01-01

.clone() — copie explicite

const original = dayjs('2024-06-15');
const copie = original.clone();

// Les deux sont indépendants
copie.add(30, 'day').format(); // 2024-07-15
original.format();              // 2024-06-15 — inchangé

Cas pratique — calculer des échéances

const commande = dayjs('2024-06-01');
const livraison = commande.add(5, 'day');
const expiration = commande.add(30, 'day');
const finMois    = commande.endOf('month');

console.log('Livraison :', livraison.format('DD/MM/YYYY'));  // 06/06/2024
console.log('Expire le :', expiration.format('DD/MM/YYYY')); // 01/07/2024
console.log('Fin de mois :', finMois.format('DD/MM/YYYY'));  // 30/06/2024

5. Comparaison

Day.js propose plusieurs méthodes pour comparer des dates entre elles.

.isBefore() et .isAfter()

const a = dayjs('2024-01-01');
const b = dayjs('2024-06-15');
const c = dayjs('2024-06-15');

a.isBefore(b);       // true
b.isAfter(a);        // true
b.isSame(c);         // true

// Comparer par unité (ignore les unités inférieures)
a.isBefore(b, 'year');   // false (même année 2024)
a.isBefore(b, 'month');  // true  (jan < juin)

b.isSame(c, 'day');      // true
b.isSame(c, 'month');    // true

.diff() — différence entre deux dates

const debut = dayjs('2024-01-01');
const fin   = dayjs('2024-06-15');

fin.diff(debut, 'day');    // 166 (jours)
fin.diff(debut, 'month');  // 5   (mois complets)
fin.diff(debut, 'year');   // 0   (moins d'un an)
fin.diff(debut, 'hour');   // 3984

// Avec décimales
fin.diff(debut, 'month', true); // 5.467...

// Date de naissance → âge
const naissance = dayjs('1995-03-20');
const age = dayjs().diff(naissance, 'year');
console.log('Âge :', age); // 29

.isValid() — vérifier une date

function validerDate(str) {
  const d = dayjs(str);
  if (!d.isValid()) {
    console.error('Date invalide :', str);
    return null;
  }
  return d;
}

validerDate('2024-06-15');    // objet Day.js valide
validerDate('2024-02-30');    // null (30 fév n'existe pas)
validerDate('abc');            // null

Tri d'un tableau de dates

const dates = [
  '2024-06-15',
  '2024-01-01',
  '2024-12-31',
  '2024-03-20'
];

// Trier du plus ancien au plus récent
const triees = dates.sort((a, b) =>
  dayjs(a).isBefore(dayjs(b)) ? -1 : 1
);
// ['2024-01-01', '2024-03-20', '2024-06-15', '2024-12-31']

// Date la plus récente
const plusRecent = dates.reduce((max, d) =>
  dayjs(d).isAfter(dayjs(max)) ? d : max
);

6. Plugins

Day.js est extensible par des plugins. Chaque plugin ajoute des fonctionnalités sans alourdir le bundle de base.

Charger les plugins via CDN

<script src="https://cdn.jsdelivr.net/npm/dayjs@1/dayjs.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dayjs@1/locale/fr.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dayjs@1/plugin/relativeTime.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dayjs@1/plugin/duration.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dayjs@1/plugin/isBetween.js"></script>
<script>
  dayjs.locale('fr');
  dayjs.extend(window.dayjs_plugin_relativeTime);
  dayjs.extend(window.dayjs_plugin_duration);
  dayjs.extend(window.dayjs_plugin_isBetween);
</script>

relativeTime — temps relatif

// Nécessite : dayjs.extend(window.dayjs_plugin_relativeTime)
dayjs.locale('fr'); // pour avoir les messages en français

const hier = dayjs().subtract(1, 'day');
const semaine = dayjs().subtract(7, 'day');
const futur = dayjs().add(3, 'hour');

hier.fromNow();         // "il y a un jour"
semaine.fromNow();      // "il y a 7 jours"
futur.fromNow();        // "dans 3 heures"

// .from(autreDate) — relatif à une autre date
const ref = dayjs('2024-01-01');
dayjs('2024-06-15').from(ref);  // "dans 6 mois"

duration — durées

// Nécessite : dayjs.extend(window.dayjs_plugin_duration)
const duree = dayjs.duration(2, 'hours').add(30, 'minutes');

duree.hours();    // 2
duree.minutes();  // 30
duree.asMinutes(); // 150
duree.humanize(); // "3 heures" (avec locale fr)

isBetween — vérifier une plage

// Nécessite : dayjs.extend(window.dayjs_plugin_isBetween)
const date = dayjs('2024-06-15');
const debut = dayjs('2024-01-01');
const fin   = dayjs('2024-12-31');

date.isBetween(debut, fin);         // true
date.isBetween(debut, fin, 'day', '[]'); // true (inclusif)

Plugins disponibles